Documentación mala o ninguna documentación son casi iguales. Una documentación buena ahorra horas de debugging y hace que nuevos miembros sean productivos en días en lugar de semanas.
README: el primer lugar donde alguien mira
Un README debe responder: qué es esto, cómo se instala, cómo se ejecuta, cómo se testa, cómo se despliega. Sin eso, el repo es inútil.
No hace falta novela. Solo responder esas preguntas concisamente.
- Qué es el proyecto en 2-3 líneas.
- Cómo instalarlo.
- Cómo ejecutarlo localmente.
- Cómo correr tests.
ADRs: registra decisiones que importan
Cada decisión arquitectónica importante debería estar registrada: por qué elegiste ese tech stack, ese patrón de diseño, ese trade-off. Sin eso, futuro tú o tu equipo repetiría la misma discusión en 6 meses.
Un ADR es documento breve: contexto, decisión, consecuencias.
- Qué problema estabas resolviendo.
- Qué alternativas consideraste.
- Por qué elegiste esa.
- Qué consecuencias tiene.
Setup local: documenta el camino feliz
Alguien nuevo no debe gastar horas descubriendo que necesita Redis, que necesita variables de entorno específicas, que necesita migrar base de datos. Todo eso debe estar en docs.
El test de documentación es: un dev completo nuevo, nunca visto el repo, ¿puede tener ambiente funcionando en 15 minutos? Si no, documenta más.
- Requisitos explícitos.
- Comandos copy-paste.
- Troubleshooting para problemas comunes.
Arquitectura visual: un diagrama vale más que 1000 palabras
Un diagrama que muestre cómo los servicios se hablan, cómo fluye datos, cómo se despliega. No necesita ser arte. Necesita ser claro.
Herramientas simples como Miro, Lucidchart o incluso PlantUML funcionan bien.
Si no puedes explicar tu arquitectura con un diagrama, probablemente no la entiendes lo suficientemente bien.
Lo que NOT debe estar en documentación
Código comentado: eso va en commit messages. Pasos que cambiar frecuentemente: eso va en README actualizado. Historia tribal de por qué algo existe: eso va en ADRs si importa.
La documentación debe ser viva, mantenida junto con el código.