En cuántos proyectos nos ha pasado que no encontramos la forma ideal de crear y mantener una documentación que resulte realmente útil?
Cuántas veces tuvimos que recurrir a una documentación para ver "cómo se había definido algo" o "cómo se había resuelto" y no lo encontramos o lo encontramos desactualizado?
Particularmente me siento muy frustrada cuando pasan estas cosas porque me doy cuenta de lo difícil que nos resulta determinar en qué medida documentar y cómo sostener esto en el tiempo.
En este artículo de Jens Schauber encontré algunos comentarios y tips que me parecen muy útiles para ordenar la idea de la práctica de la documentación durante los proyectos.
Comparto un resumen de lo que dice el autor:
El concepto que me pareció más interesante es la visión que nos da sobre la documentación y que expresa al final de su artículo:
Según el autor, una de las utilidades de la documentación es la de servir como guía a los nuevos. Para quienes llevan tiempo trabajando en un proyecto es fácil identificar cuáles son los puntos más importantes, riesgosos o complejos. Alguien nuevo seguramente se encuentre perdido en un territorio desconocido. Tener un "mapa" de ese terreno ayudará a que el nuevo integrante pueda ubicarse y detectar sin mucho esfuerzo los puntos estratégicos, aún cuando ese mapa no esté del todo actualizado.
Por otro lado, aún cuando se conozca bien el territorio, no siempre es fácil determinar la mejor forma de moverse entre dos puntos. Un mapa puede ayudar a darnos una visión más clara y rápida de ese problema.
A veces podemos encontrar en ese territorio "features" que no se sabe muy bien para qué estan. Poner anotaciones en el mapa ayuda a detectar fácilmente si esos features deben quedar (y por qué) o simplemente son basura que espera ser removida.
Por último, Schauber nos dice que la documentación debe ser usada,
Usar la documentación sirve para notar los problemas y, a partir de eso, abordarlos.
Además, la documentación debe ser fácilmente accesible y comunicada al resto: desde imprimir y pegar en las paredes de la oficina las actualizaciones o definiciones más importantes, hasta poner un link en algún lugar al que los involucrados tengan acceso (servers, intranets, etc.) o enviar mail, usar RSS feeds, etc., debemos buscar la forma de hacer llegar a todos las notificaciones de cambio si queremos que realmente tenga sentido el tiempo que utilizamos en mantener una documentación medianamente actualizada.
Artículo de Jens Schauber (en inglés): The purpose of documentation
Twittear Seguir a @3p_ar
Cuántas veces tuvimos que recurrir a una documentación para ver "cómo se había definido algo" o "cómo se había resuelto" y no lo encontramos o lo encontramos desactualizado?
 |
| (fuente www.freevector.com) |
En este artículo de Jens Schauber encontré algunos comentarios y tips que me parecen muy útiles para ordenar la idea de la práctica de la documentación durante los proyectos.
Comparto un resumen de lo que dice el autor:
El concepto que me pareció más interesante es la visión que nos da sobre la documentación y que expresa al final de su artículo:
La documentación no debe ser un objetivo por sí misma. Es una herramienta para el entendimiento común y sólo debería ser creada cuando realmente aporta valor a nuestro trabajo. No debemos confundir la herramienta con el propósito que debe tener.
- Cuando creamos documentación es necesario clarificar el propósito, debemos preguntarnos qué problema esperamos resolver con eso, qué problema trata de resolver esa documentación y resolver ese problema en la misma documentación.
- Y no sólo eso, cuando se crea una documentación hay que pensar y tener claro desde el principio cómo hacer para mantenerla actualizada. Algo que sugiere Schauber es incluir esa tarea como parte de la definición de "Done! o agendar tiempo a intervalos regulares para dedicar a la misma.
- Debemos elegir formas de documentar que sean fáciles de matener: una wiki puede ser una buena idea, documentar en el código puede ser aún mejor.
- Y algo para tener en claro según el autor:
"lo que decididamente no sirve es tener largos procesos de aprobación de la documentación, que hará que nadie quiera actualizarlos a menos que sea obligado a hacerlo ...."
Territorios y mapas
Creo que a partir de lo anterior podemos entender mejor algunos de los tips que nos da, haciendo una analogía entre la documentación y los mapas.Según el autor, una de las utilidades de la documentación es la de servir como guía a los nuevos. Para quienes llevan tiempo trabajando en un proyecto es fácil identificar cuáles son los puntos más importantes, riesgosos o complejos. Alguien nuevo seguramente se encuentre perdido en un territorio desconocido. Tener un "mapa" de ese terreno ayudará a que el nuevo integrante pueda ubicarse y detectar sin mucho esfuerzo los puntos estratégicos, aún cuando ese mapa no esté del todo actualizado.
Por otro lado, aún cuando se conozca bien el territorio, no siempre es fácil determinar la mejor forma de moverse entre dos puntos. Un mapa puede ayudar a darnos una visión más clara y rápida de ese problema.
A veces podemos encontrar en ese territorio "features" que no se sabe muy bien para qué estan. Poner anotaciones en el mapa ayuda a detectar fácilmente si esos features deben quedar (y por qué) o simplemente son basura que espera ser removida.
Por último, Schauber nos dice que la documentación debe ser usada,
la documentación que no se usa es inútil
Usar la documentación sirve para notar los problemas y, a partir de eso, abordarlos.
Además, la documentación debe ser fácilmente accesible y comunicada al resto: desde imprimir y pegar en las paredes de la oficina las actualizaciones o definiciones más importantes, hasta poner un link en algún lugar al que los involucrados tengan acceso (servers, intranets, etc.) o enviar mail, usar RSS feeds, etc., debemos buscar la forma de hacer llegar a todos las notificaciones de cambio si queremos que realmente tenga sentido el tiempo que utilizamos en mantener una documentación medianamente actualizada.
Artículo de Jens Schauber (en inglés): The purpose of documentation
Twittear Seguir a @3p_ar
