[#ALM] Documentar o no documentar? (te corto los dedos !!!)

Buenas,

empezamos con una afirmación de esas que solo los fanáticos y cortos de vista suelen soltar con tanto placer:

“Generar documentación en un proyecto no sirve absolutamente para nada”

o alguna de sus variantes, como “La documentación es una pérdida de tiempo”, “Documentar es de perdedores”, “…”, etc. Como soy una persona de grises, voy a agregar un par de matices a esta línea de pensamiento.

El problema con la documentación no son sus bases, yo siempre me voy al nivel más básico que sería algo así como:

“Una persona nos dice lo que necesita, alguien lo escribe y luego lo construye”

El problema es que durante mucho tiempo, muchas personas se dedicaron a invertir más tiempo en definir el CÓMO se debería redactar esta información, en lugar de escribir el QUE necesita una persona. A partir de este punto se crearon procesos en los cuales la burocracia de los mismos hizo que los resultados finales fueran imposibles. Existía una distancia tan grande entre el momento en el que se redactada el QUE hacer, y el momento en el que se entregaba el resultado, que por lo general se escribía sobre peras y se entregaban manzanas. Pero claro, el problema no era la documentación en sí, sino el proceso sobre el que se basaba la misma. Vamos que era un problema de comunicación.

Actualmente, las escuelas ágiles proponen unos mecanismos mucho más simples para redactar esta información y a partir de los mismos comenzar una fase de construcción que permite en un tiempo menor validar lo redactado. (User Stories, Product Backlogs, etc.)

Entonces volvemos al punto que dicta el título de este post:

¿Cómo encontrar el nivel justo de documentación para un proyecto?

La respuesta es 100% ambigua:

“Depende de cada proyecto”.

Mi recomendación es:

Comienza siempre con un mínimo de documentación para un proyecto. Por ejemplo, solo creando user Stories.

Comenzar un enfoque less-to-much, es decir comenzar con simples User Stories y a partir de allí comenzar a completar la misma a medida que se requiere. Este enfoque nos permite tener un mínimo de documentación y en el caso de que sea necesario, generar automáticamente los documentos que se requieren sobre este mínimo. Por ejemplo, si utilizamos las herramientas de modelado de Visual Studio 2012, podremos automatizar el proceso de generación de documentación para generar todo tipo de artefactos UML que suelen ser los requeridos. Este caso además tiene la ventaja de que lo que estamos generando refleja 100% (o casi) el producto que es nuestro código.

Usualmente en los entornos donde se requiere cumplir con altos niveles de documentación, la misma es solo para completar formalidades, pero pocas veces para utilizarla como realmente se define en el proceso. Muchas veces he estado en situaciones donde se discutía la funcionalidad X o Y de un producto sobre la documentación del mismo, y en realidad el producto generado no reflejaba la documentación inicial. Es por eso, que el 2do consejo es el siguiente:

“Intenta automatizar siempre los mecanismos de generación de documentación para que la misma se genere a partir del código”

Técnicas como Behavior Driven Development o Test Driven Development, son excelentes drivers para tener un modelo en el que la documentación pueda “surgir” de una forma natural del código (y de los tests

Así que ya sabes, documentar no es tan malo como parece; lo delicado es encontrar la forma correcta de hacerlo para que en un proyecto todo el mundo “entienda lo mismo”.

Último ejemplo: hace poco participé en un proyecto donde trabajamos con personas de varias ciudades de España. Como éramos varios tirando líneas al mismo tiempo, después de un par de meses todo el mundo se manejaba de forma natural entre los 40 o más proyectos de la solución (estoy hablando de tener muchas tecnologías mezcladas en un mismo sitio). En determinado momento se incorporaron personas de USA para el Release Management y me di cuenta de que si bien yo tenía muy en claro, lo que incorporábamos en las versiones 1.0, 1.1, 1.2, etc.; esta información no era muy clara si no sabías como “leer los comentarios” y la estructura de nuestros PBIs y Tareas en el TFS. Así que en ese momento, se me plantearon 2 opciones: o intentaba explicarles nuestro día a día al equipo de packaging de USA o … creaba un archivo versions.txt.

Obviamente opté por la la 2da opción. Mi única tarea adicional de documentación consistía en completar un archivo de texto con los puntos más relevantes incluidos en cada nueva rama del producto. Esta tarea era un paso adicional más cada vez que creaba una rama de RELEASE y era el punto donde el equipo de Packaging identificaba los elementos que se incluían en cada versión. Yo considero esta tarea una tarea de documentación y no reniego de la misma. Veo que los resultados y ventajas que me brinda son mucho más valiosos que otras opciones.

Nota: Si no te suena el concepto de releases por ramas o te falta algo de contexto, mi libro de ALM te puede ayudar. Aquí-

Saludos @ Home

El Bruno