La mayoría de los equipos no tiene un problema de documentación. Tiene un problema de utilidad.
El problema rara vez es la cantidad total de documentación. El problema es si las decisiones correctas están capturadas en un lugar donde el equipo realmente pueda usarlas.
Qué sí vale la pena documentar
La documentación crea valor cuando ayuda a entender:
- límites arquitectónicos,
- decisiones importantes de producto o técnicas,
- pasos de setup fáciles de olvidar,
- caveats de integraciones,
- y restricciones no obvias.
Qué suele convertirse en desperdicio
Las explicaciones paso a paso de código que cambia cada semana envejecen mal. Los documentos largos que nadie actualiza suelen ser peores que notas cortas conectadas a la verdadera fuente de verdad.
Mejores principios de documentación
La buena documentación es:
- corta,
- específica,
- cercana al sistema que describe,
- y mantenida solo mientras siga ayudando.
Cierre
La documentación útil debe quitar fricción. Si no reduce confusión, riesgo o tiempo de onboarding, probablemente está demasiado lejos del trabajo real.