Blog —
Cuánto cuesta no documentar
La documentación parece un gasto hasta que se va la persona que sabía cómo funcionaba todo.
En la práctica, documentar siempre pierde contra entregar una funcionalidad más. Es entendible: la funcionalidad se ve en pantalla y la documentación no se ve en ninguna parte. El costo llega más tarde, cuando entra alguien nuevo al equipo o cuando se va la persona que tenía todo en la cabeza.
El problema no es el código
El código se puede leer. Lo que no se reconstruye leyendo son las decisiones: por qué se eligió una base de datos y no otra, qué alternativa se probó y funcionó mal, qué caso particular explica esa condición que parece estar de más.
Lo mínimo que conviene tener escrito
- Cómo levantar el proyecto en una máquina nueva, paso a paso.
- El modelo de datos y qué significa cada tabla.
- Los accesos: dónde están, quién los tiene y cómo se renuevan.
- Las decisiones importantes, en un párrafo cada una.
- Qué hacer cuando el sistema se cae.
Escribirla en el momento
La documentación que se deja para el final del proyecto no se escribe nunca. Una página por decisión, redactada el mismo día en que se tomó, lleva quince minutos y después queda disponible para todo el equipo.
Una forma de probar si alcanza
Pedile a alguien que no trabajó en el proyecto que lo levante siguiendo únicamente lo que está escrito. Cada vez que tenga que preguntar algo, ahí hay una línea para agregar.
