Documentazione operativa di un repository

Manuali che servono a far girare il progetto: avviarlo in locale, metterlo in produzione, capire cosa si è rotto quando si rompe. Il lettore è chi manutiene, non chi valuta: non gli serve sapere che il progetto è scalabile, gli serve il comando esatto e la variabile esatta.

Regola d'oro: si documenta solo ciò che i file del repository dimostrano. Ogni affermazione operativa — una porta, una variabile, un comando, un dominio, un passo di deploy — deve essere riconducibile a un file preciso. Quando non lo è, l'esito è NON DEDUCIBILE, ed è un esito legittimo e frequente. Un README con dieci sezioni verificate e tre marcate NON DEDUCIBILE vale molto più di uno completo per metà inventato: è l'unico modo in cui questa documentazione resta affidabile a sei mesi di distanza.

Quando NON usarla