La documentación que nadie consulta no es un problema de disciplina del equipo: es un problema de formato. Estas son las piezas que sí se usan.
El criterio: documentar lo que no se deduce del código
El código dice qué hace el sistema. Un desarrollador competente puede leerlo. Lo que no puede deducir es por qué se decidió así, qué alternativas se descartaron y con qué criterio, y qué pasa si se cambia.
Documentar lo primero produce texto redundante que se desactualiza. Documentar lo segundo produce el material que evita que el siguiente equipo repita un error ya cometido.
Las cinco piezas que sí se consultan
Documentar limitaciones genera confianza, no la resta
Existe el temor de que dejar por escrito lo que el sistema no hace se lea como una debilidad. En la práctica ocurre lo contrario: un equipo que documenta sus límites demuestra que los conoce.
El daño real lo produce la limitación no documentada que se descubre en producción, cuando ya nadie recuerda si fue una decisión o un descuido.
Mantenerla viva
La documentación que vive en un repositorio separado del código se desactualiza en semanas. La que vive junto al código y se revisa en el mismo proceso que los cambios tiene una posibilidad real de mantenerse vigente.
La regla operativa que funciona: un cambio que altera una decisión documentada no se aprueba sin actualizar el registro correspondiente.