Documentación que la gente lee de verdad
Cuatro documentos que bastan
Un archivo de inicio. Qué es, cómo ejecutarlo en local, cómo ejecutar las pruebas y a quién preguntar. Debe ser preciso: es el documento que se comprueba en cada incorporación.
Decisiones de arquitectura. Una página por cada decisión significativa: contexto, opciones, qué se eligió y por qué. Breve y con fecha.
Operaciones. Qué hacer cuando algo se rompe, cómo desplegar, cómo revertir.
Interfaz. Desde el propio código, para que no envejezca.
Cómo mantenerla fresca
Documentación que vive cerca del código y se actualiza en la misma solicitud de fusión. Un documento en otro sitio envejece en dos meses, y lo que es peor: sigue pareciendo autoritativo.
Qué no documentar
Lo que el código dice claramente. Un comentario que describe una línea sobra; un comentario que explica por qué se eligió un enfoque inusual vale su peso en oro.
En profundidad
Comprueba el archivo de inicio en cada incorporación: haz que un recién llegado lo siga al pie de la letra y anote cada sitio donde se atascó. Es la única forma de encontrar los supuestos silenciosos que todos los veteranos guardan en la cabeza y nadie escribió.