Quanto è importante la documentazione?

Tutti concordano sul fatto che la documentazione è importante.

Tuttavia ...

Molti programmatori ritengono che il codice debba essere "auto-descrittivo" che il codice stesso debba fungere da documentazione e che pertanto non sia necessaria la documentazione. Ma questo è vero solo in una certa misura. Il codice non documenta in modo adeguato le relazioni tra i componenti. È irragionevole chiedere al programmatore di seguirti per guadare attraverso una base di 100.000 codici di codice cercando di capire cosa sono supposti tutti quegli oggetti astratti di fabbrica che hai scritto da fare.

La documentazione richiede tempo. La prima priorità nella maggior parte delle aziende è la spedizione, non la documentazione. Quando c'è documentazione, spesso documenta i loro processi aziendali o fornisce una guida per l'utente, ma non le relazioni tra i componenti software.

La documentazione è un'altra cosa che deve essere mantenuta. A differenza del codice di auto-documentazione, la documentazione deve essere aggiornata, altrimenti non sarà più d'accordo con il codice (che è la vera fonte della verità ).

Per tutti questi motivi, la documentazione viene spesso trascurata.

Una documentazione ben progettata aggiornata, corretta e è un must. Tuttavia, se non soddisfa questi tre criteri, allora è peggio che inutile: è un inferno tempo / disco / anima-succhiamento.

Uno dei problemi che trovo nei progetti di medie / grandi dimensioni è che c'è un feticcio sulla documentazione, ma assolutamente nessuna idea di quale documentazione è per , cioè:

• La documentazione è non una casella di spunta.
• La documentazione è non un "documento" Microsoft Word contenente principalmente screenshot di installazione / configurazione guidata. (Il 99% della "documentazione" che trovo (o è richiesta da me) è di questo tipo).
• La documentazione è un grafico in diretta di tutte con annotazioni (sia in-system che esterne)
.
• La documentazione è una wiki live creata in modo collaborativo da tutti gli stakeholder dell'IT. Nota che non ho detto progetto.
• La documentazione deve includere tutte le opzioni di configurazione e, per ciascuna di esse, deve specificare quale valore ha o esattamente dove e come che il valore può essere acquisito.
• La documentazione deve anche indicare perché l'opzione X ha il valore Y e se la decisione è tecnica (ad esempio stiamo usando jumbo frame perché aumenta le prestazioni e riduce il carico del sistema ) o politico (ad esempio, non stiamo utilizzando la negoziazione automatica perché ci sono state esperienze negative su schede / switch Versione 0.0.1 di 20 anni fa).

Il più possibile, non "documentare" . Fai un grafico, documentalo sul wiki e carica i dati da un CMDB.

Il punto è che il documento è molto più utile per te (il nuovo tipo) rispetto alle persone che ci lavorano da anni. Ho prodotto documenti simili e li ho anche mantenuti per un po '; ma sospetto che se qualcuno avesse cercato di riprendersi, avrebbero avuto delle difficoltà.