La documentazione tecnica fallisce in un modo preciso e prevedibile. Qualcuno ne scrive moltissima durante due settimane tranquille, il sistema cambia, nessuno la aggiorna e nel giro di un anno il documento afferma con sicurezza cose false. Da quel momento vale meno di niente, perché chi si fida agisce su informazioni che non valgono più.

La reazione consueta è spingere a scriverne di più, il che non fa che accelerare lo stesso fallimento. La reazione utile è scriverne meno e scegliere cosa, perché il vincolo non è lo sforzo di scrittura. È la manutenzione.

L’unico criterio duraturo per capire se un documento debba esistere: qualcuno se ne accorgerà quando diventerà sbagliato? Una guida al deploy viene usata e i suoi errori emergono subito. Una descrizione di venti pagine di un sottosistema viene letta una volta sola e i suoi errori emergono diciotto mesi dopo, quando qualcuno ci agisce sopra. I documenti che nessuno esercita marciscono in silenzio, e sono proprio quelli da lasciare non scritti.

Perché invecchia

Tre meccanismi, e uno solo è pigrizia.

La documentazione vive lontano da ciò che descrive. Una modifica al codice non è una modifica a una pagina wiki, quindi tenerli allineati dipende dal fatto che qualcuno se lo ricordi. Quel ricordo viene meno, puntualmente, e più il documento sta lontano dal codice più in fretta accade.

Descrive l’implementazione invece dell’intento. Un documento che spiega come funziona oggi un componente viene invalidato da ogni refactoring. Uno che spiega perché il componente esiste e quale vincolo soddisfa sopravvive, perché il motivo cambia molto meno spesso del codice.

Non è di nessuno. La documentazione che appartiene a tutti non appartiene a nessuno, e non esiste un momento in cui la sua correttezza diventi il problema di qualcuno in particolare.

I rimedi discendono dalle cause: tenerla vicino al codice, scrivere l’intento invece del meccanismo, e dare a ogni documento un responsabile con nome e cognome più un’occasione concreta in cui viene usato.

La documentazione tecnica che vale la pena mantenere

Quattro documenti coprono quasi tutto il valore. Tutto il resto deve giustificarsi.

Un README che ti mette in moto. Cos’è questo progetto, come si configura, come si lanciano i test, come si rilascia. Viene usato di continuo, quindi gli errori emergono in fretta. È il documento con il rendimento più alto di qualsiasi repository e anche quello che più spesso resta un modello di progetto che nessuno ha mai modificato.

Una panoramica dell’architettura. Quali sono i pezzi principali, come comunicano e perché sono separati. Una pagina e un diagramma, che descrivono la forma invece del dettaglio. Cambia di rado e risponde alla domanda che altrimenti ogni nuovo arrivato ricostruisce da solo leggendo tutto.

I registri delle decisioni. Note brevi che fissano una decisione, le alternative valutate e il motivo della scelta. Nel gergo tecnico si chiamano quasi sempre Architecture Decision Record, o ADR. Si aggiungono soltanto, non vanno mai aggiornate, e prevengono la forma più costosa di lavoro ripetuto: ridiscutere male una questione già chiusa perché nessuno ricorda più il vincolo che l’aveva chiusa.

I runbook per ciò che si rompe. Un runbook è la procedura operativa di intervento: come diagnosticare e risolvere i guasti che avete davvero avuto. Si scrive subito dopo un incidente, finché è fresco, e si mette alla prova al successivo. Un runbook che nessuno ha mai seguito è una bozza.

Nessuno di questi quattro documenti descrive come funziona il codice. A quello serve il codice stesso, e qualsiasi prosa che lo duplichi diventa una seconda fonte di verità destinata a contraddire la prima.

Scrivere per chi è stanco e ha fretta

Quasi tutta la documentazione tecnica viene letta sotto pressione, da qualcuno con una domanda precisa, spesso fuori orario. Scrivete per quel lettore, non per uno che ha tempo.

Prima la risposta, poi la spiegazione. Chi legge il vostro runbook alle due di notte ha bisogno del comando, e solo dopo del ragionamento. Il contesto prima della risposta è una struttura che va bene a chi scrive e a nessun altro.

Siate concreti. Comandi veri, percorsi veri, valori di esempio veri. «Configurare le variabili d’ambiente appropriate» non è un’istruzione, è la descrizione di un’istruzione.

Dite cosa andrà storto. Le modalità di guasto e il loro aspetto sono spesso il contenuto più prezioso, perché sono esattamente ciò che il lettore sta vivendo in quel momento.

Tenetela abbastanza corta da restare vera. Ogni frase è un debito di manutenzione. Una pagina che copre il caso comune e ammette i propri limiti batte un documento che copre tutto ed è sbagliato in tre punti.

La stessa disciplina che rende una pagina citabile da un sistema di recupero la rende usabile a un collega esausto, ed è esattamente il punto che la nostra guida su perché i tuoi contenuti si posizionano ma non sono citati solleva a proposito dei testi pubblici.

Tenerla in vita

Mettetela nel repository. Un documento che viaggia con il codice viene modificato nella stessa revisione del codice, e questo è l’unico meccanismo che tiene i due allineati in modo affidabile.

Rivedetela in code review. Se una modifica rende sbagliato un documento, quello è un commento di revisione come un altro. È l’abitudine con la leva più alta a disposizione e non costa nulla.

Testate ciò che si può testare. Le istruzioni di installazione che girano in una pipeline smettono di essere velleitarie. Se il vostro README sostiene che tre comandi producono un sistema funzionante, fatelo dimostrare da un job.

Cancellate senza esitare. Un documento sbagliato è peggio di uno mancante, perché gli si dà fiducia. Quando qualcosa invecchia e nessuno lo sistemerà, rimuovetelo e annotate cosa è andato perso.

Datate ciò che scade. Tutto ciò che contiene un numero di versione, un prezzo o una dipendenza esterna dovrebbe portare una data, così il lettore può giudicare se fidarsi.

A cosa serve davvero

La documentazione è il meccanismo con cui la conoscenza smette di dipendere dalle singole persone. È tutto il beneficio, ed è il motivo per cui l’argomento a favore della scrittura è economico e non estetico.

Un sistema che una sola persona sa rilasciare ha un tempo di ripristino pari alla disponibilità di quella persona. Un componente che nessuno sa giustificare finisce ricostruito oppure conservato per superstizione. Entrambi compaiono come rilievi nella due diligence tecnica, entrambi allungano l’inserimento degli sviluppatori, ed entrambi sono lo stesso problema vestito in modo diverso.

Mecanik redige questi documenti come parte del passaggio di consegne in ogni incarico, nell’ambito del nostro lavoro di sviluppo software. Il documento che finisce per essere usato è quasi sempre più corto di quello che era stato richiesto.

Domande frequenti

Perché la documentazione tecnica diventa obsoleta? Perché vive lontano dal codice, quindi l’allineamento dipende dal fatto che qualcuno se lo ricordi; perché descrive l’implementazione invece dell’intento, quindi ogni refactoring la invalida; e perché non è di nessuno, quindi la sua correttezza non è mai il problema specifico di qualcuno. Tenerla nel repository e rivederla insieme alle modifiche al codice risolve tutte e tre le cause.

Quale documentazione dovrebbe mantenere un team software? Quattro cose coprono quasi tutto il valore: un README che mette in funzione il sistema, una panoramica dell’architettura di una pagina che spiega forma e ragionamento, registri delle decisioni in sola aggiunta che fissano perché sono state fatte certe scelte, e runbook per i guasti che avete davvero avuto. Le descrizioni di come funziona il codice non sono nell’elenco.

Che cos’è un registro delle decisioni? Una nota breve che fissa una decisione, le alternative valutate e il motivo della scelta. Poiché registra un momento invece di uno stato corrente, non ha mai bisogno di aggiornamenti, e impedisce che questioni già chiuse vengano ridiscusse male da persone che non ricordano più il vincolo che le aveva chiuse.

Come andrebbe scritta la documentazione tecnica? Per qualcuno stanco, sotto pressione e alla ricerca di una cosa sola e precisa. Prima la risposta e poi la spiegazione, comandi veri e percorsi veri invece delle loro descrizioni, dire cosa va storto e che aspetto ha, e tenerla abbastanza corta da restare vera.

La documentazione obsoleta va cancellata? Sì, se nessuno la sistemerà. Un documento sbagliato è peggio di uno mancante, perché il lettore si fida e agisce di conseguenza. Cancellatelo e annotate cosa è andato perso, e datate tutto ciò che contiene un numero di versione, un prezzo o una dipendenza esterna, così i lettori possono giudicare da soli.