La bitácora de proyecto

Por Carlos Blé Jurado

¿Quién dijo que “agile” significa “sin documentación”? La documentación es importante, lo que dice la agilidad es que es más prioritario poner en producción software que funciona, que escribir documentación. Pero la documentación hay que escribirla también.

Un documento que cada vez tiene más valor para nosotros es la bitácora del proyecto. Un fichero al que todo el equipo tiene acceso y que está ordenado cronológicamente, de manera que arriba del todo aparece lo último y más abajo lo más antiguo. No importa si es un Google Docs compartido o si es un fichero markdown versionado dentro del repositorio. Nosotros encontramos muy práctico que sea parte del repositorio de código fuente y esté versionado con Git, al igual que las demás fuentes. Bitácora.md. Lo escribimos en castellano, a diferencia del código fuente, que lo escribimos en inglés. En cada entrada del fichero anotamos:

• Fecha: Día y hora
• Quiénes escriben: Persona[s] que están escribiendo esta entrada
• Asunto: típicamente, alguna de las siguientes categorías:
  • Reunión: toma de requisitos, demo, retrospectiva…
  • Subida a producción: nueva versión lanzada.
  • Incidencia en producción: hubo que corregir un problema en producción.
  • Decisiones técnicas: por qué hemos decidido hacer o no hacer algo.
• Contenido:
  • En las reuniones recogemos qué personas estaban, un resumen de lo que se habló y, sobre todo, las acciones que se acordaron realizar. Este resumen, además, lo enviamos por email a todas las personas que participaron en la reunión. Sirve para que todo el mundo vea que durante la reunión estuvimos prestando la máxima atención y para reafirmar que todos entendemos las siguientes acciones a tomar.
  • En una subida a producción anotamos el changelog, qué novedades hay. Pueden ser nuevas funcionalidades o cambios en las existentes, además de retoques en la UX, bugfixes y cualquier tipo de mejora. No pretende repetir lo mismo que ya hay en los commmits del control de versiones, sino resumirlo con la información más importante. Por ejemplo, si hay algún cambio importante de versión en las dependencias que requiera volverlas a descargar y limpiar la cache, o cualquier otro detalle que ahorre problemas a cualquiera del equipo que intenta usar esta última version. Si ha cambiado alguna configuración del entorno…
  • Incidencias: ocurrió un accidente. Lo arreglamos y no queremos que vuelva a ocurrir, así que analizamos el problema y escribimos la solución para que no se repita. Importante explicar bien el por qué de las cosas. Si se trata de bugs en el código, añadimos tests automáticos que demuestran el bug y añadimos los nombres de estos tests a este apartado de la bitácora. Esto nos permite localizar rápidamente tests que fueron añadidos como resultado de algún bug, que suelen ser un buen hilo del que tirar para practicar más Exploratory, Testing y descubrir más bugs.
  • Decisiones técnicas: el código más limpio del mundo es incapaz de contarle al lector, por qué se descartó alguna solución que a priori podría parecer más obvia o conveniente que la solución elegida. Siempre que se dedica tiempo a analizar un problema y se decide tomar una solución, es importante que el razonamiento seguido esté reflejado en algún lugar, para que en el futuro se evite repetir el mismo proceso de toma de decisiones. Las preguntas clave son ¿Por qué?, ¿para qué?, ¿por qué no?, ¿qué alternativas descartamos?

El ejercicio de dejar escrito los eventos importantes que ocurren durante la vida del proyecto nos permite entender en mayor profundidad lo que está ocurriendo y es una forma de evitar que la historia se repita cuando las cosas se tuercen.

Aquellos que no conocen la historia están condenados a repetirla.