Documentación ágil

miércoles, 7 de mayo de 2014

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?

(fuente www.freevector.com)
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:
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



        










Leer más...

Cuando la solución es el problema (cómo prevenir la sobre-ingeniería)

lunes, 5 de mayo de 2014

Hace pocos días leí un artículo que me pareció muy útil y cierto sobre algo que podemos reconocer fácilmente como "pecado cometido" en nuestros propios proyectos: lo difícil que resulta determinar cuándo llegamos a un punto en que estamos haciendo sobre-ingeniería o agregando features que no siempre son imprescindibles.

La visión que tiene el autor - Aneesh Karven - y los consejos que da para reconocer y afrontar este problema son muy directos y pueden ser de gran ayuda para empezar a observarnos internamente.
Les comparto aquí un resumen en español del artículo (original en inglés):

Un primer punto a destacar de la nota es que el autor entiende que el problema de muchos profesionales del software es que tienen un "exceso de confianza en la herramienta que usan y les es familiar" (por eso lo relaciona con la Ley del Martillo) lo que hace que piensen que aquello que puede ser la "solución al problema" en realidad resulta ser una exacerbación del problema. Esto hace que se generen features y fixes que dañan más que lo tienen que curar debido a las consecuencias inesperedas que suelen provocarse.

Otra de las cosas que me pareció interesante es lo que Karven sugiere como solución a estos casos de sobre-ingeniería en los que se suele caer. Como punto de partida nos dice que es fundamental un cambio de mentalidad.


Y a partir de este cambio sugiere implementar estos 2 consejos prácticos:

Preguntarse 3 cosas

Cuestionarse varias cosas antes de escribir una sola línea de código. El autor recomienda tener en cuenta estas 3 preguntas de Baumer and Silverman (en su libro When the implication is not to Design)

  1. Podría la tecnología ser reemplazada por un enfoque igualmente viable pero no tecnológico?
  2. Una intervención tecnológica puede resultar en más problemas o daños que los que podría provocar la situación actual ?
  3. Es la tecnología (en este caso) un sustituto "menor" de la solución real a aplicar?

Cambiar la cultura de la compañía 

Según Karven los siguientes valores culturales pueden ser útiles para prevenir la expansión descontrolada de features:

  • Valorar el "no hacer algunas cosas" (o "no hacer cosas"):  aquí sugiere instalar conversaciones dentro de la compañía sobre "MENOS ES MÁS". Considerar qué features se pueden eliminar para mejorar el producto Esta frase que Karven cita en su artículo me pareció muy apropiada: "La perfección es finalmente alcanzada no cuando ya no hay más para agregar sino cuando ya no hay más para sacar." (Antoine de Saint Exupéry)
  • Documentar los caminos NO explorados: para superar la mencionada Ley del Martillo nos sugiere documentar lo que NO SE ESTÁ HACIENDO y por qué no lo hacemos, o sea, tener bien visibles las soluciones NO TOMADAS.


Continuar creciendo

A lo que se refiere en este caso es a lograr un cambio de perspectiva. Practicar esto es "practicar la humildad y precisión". El software, la gente que lo usa y las situaciones que crea pueden ser más complejas de lo que podemos imaginar. Debemos esperar sorpresas y resultados no lineales de cada intervención."
Esta otra frase dentro del artículo expresa muy bien lo que nos quiere decir "mirar en todos los rincones antes de empezar a intervenir.".

Personalmente encontré en este artículo muchos puntos clave con los que podemos identificarnos quienes trabajamos en este ámbito desde hace tiempo y creo que la mayor dificultad está en poder entender claramente que un cambio de rumbo en estas prácticas (a veces no vistas como un problema) pueden mejorar muchísimo el resultado de nuestro trabajo. Es muy común pensar que cuanto más agreguemos y tengamos contemplado dentro de nuestro código, mejor va a ser para el cliente. Pero me pareció muy clara la visión totalmente opuesta que Karven expone sobre esta creencia.

Como dice mi maestro de pintura: "una obra no se termina, simplemente se abandona", lo difícil es tener claro cuál el punto justo para hacerlo.


Este es el artículo original en inglés When the solution is the problem - How to prevent over-engineering & useless features

En el mismo sentido de este artículo, este otro artículo del autor puede ser de utiilidad How to cut features and enjoy it


        


Leer más...