In molte organizzazioni la documentazione vive in un posto e il lavoro in un altro: le procedure in un documento condiviso che nessuno aggiorna, le istruzioni in una wiki a cui si accede di rado, le note decisive nelle email. Il risultato è noto a tutti: documentazione vecchia, di cui ci si fida poco.
L'approccio chiamato docs as code propone di trattare la documentazione con gli stessi strumenti e le stesse abitudini del codice: file di testo, controllo di versione, revisione prima della pubblicazione, controlli automatici. Non serve essere programmatori per adottarlo, ma bisogna accettare di lavorare con file di testo invece che con un editor visuale.
Gli elementi
- File di testo semplice, di solito Markdown, a volte reStructuredText o AsciiDoc.
- Git per tenere la storia di ogni modifica, sapere chi ha cambiato cosa e tornare indietro.
- Revisione tramite richieste di modifica (pull request o merge request): nessuna pagina cambia senza che un'altra persona l'abbia letta.
- Un generatore di siti statici che trasforma i file in un sito navigabile con menu, ricerca e indice.
- Controlli automatici che verificano link, ortografia e stile a ogni modifica.
Perché funziona
Il vantaggio principale è che la documentazione si aggiorna nello stesso momento in cui cambia la cosa documentata. Se una procedura di backup cambia, la modifica alla configurazione e quella alla documentazione entrano nella stessa richiesta e vengono riviste insieme. Chi rivede può rifiutare una modifica tecnica che non aggiorna le istruzioni.
Altri vantaggi concreti:
- la storia di Git risponde a domande come «da quando la procedura dice così?»;
- i testi si possono cercare e modificare in blocco con gli strumenti normali;
- nessuna dipendenza da una piattaforma: i file restano leggibili anche senza il sito.
Una struttura tipica
progetto/
├── docs/
│ ├── index.md
│ ├── installazione.md
│ ├── guide/
│ │ ├── primo-accesso.md
│ │ └── backup-giornaliero.md
│ ├── riferimento/
│ │ └── configurazione.md
│ └── img/
└── mkdocs.yml
Un'organizzazione molto usata divide i contenuti per scopo: tutorial per chi inizia, guide pratiche per compiti specifici, riferimento per l'elenco completo di opzioni e parametri, spiegazioni per il perché delle scelte. Tenere separati questi quattro tipi evita pagine che provano a fare tutto e non fanno bene niente.
Scegliere il generatore
| Strumento | Formato | Punti di forza | Adatto a |
|---|---|---|---|
| MkDocs (con il tema Material) | Markdown | Configurazione semplice, ricerca integrata, aspetto curato | Manuali, procedure, documentazione interna |
| Sphinx | reStructuredText, Markdown con estensione MyST | Riferimenti incrociati potenti, uscita anche in PDF, documentazione automatica del codice Python | Progetti software estesi |
| Docusaurus | Markdown, MDX | Versioni multiple, blog integrato | Documentazione di prodotti |
| Hugo | Markdown | Velocità, grande flessibilità | Siti misti tra documentazione e contenuti |
Per iniziare, MkDocs è la scelta con meno attrito: un file di configurazione, una cartella di file Markdown e due comandi.
pip install mkdocs-material
mkdocs serve # anteprima locale che si aggiorna a ogni salvataggio
mkdocs build # genera il sito statico nella cartella site/
I controlli automatici
La forza del metodo emerge quando si aggiungono verifiche che partono da sole a ogni modifica:
- Link interrotti: strumenti dedicati controllano che ogni collegamento interno ed esterno funzioni.
- Formattazione Markdown: markdownlint segnala titoli saltati, elenchi incoerenti, spazi superflui.
- Stile e terminologia: Vale applica regole di scrittura definite dal gruppo, per esempio «si scrive email, non e-mail» o «evitare semplicemente».
- Ortografia: correttori da riga di comando con un dizionario dei termini tecnici del progetto.
- Compilazione: se il sito non si genera, la modifica non viene accettata.
Queste verifiche girano nei sistemi di integrazione continua delle piattaforme Git e riportano gli errori direttamente nella richiesta di modifica.
Le difficoltà reali
Docs as code non è adatto a tutto. Le persone non tecniche possono trovare scomodo Git; per loro conviene offrire l'editor web della piattaforma, che permette di modificare un file e aprire una richiesta senza installare nulla. Documenti molto impaginati, come brochure o contratti, restano meglio in un programma di videoscrittura.
Nel mio lavoro lo uso per tutto ciò che descrive sistemi e procedure: configurazioni, guide operative, runbook per gli interventi. È lì che una documentazione aggiornata fa davvero la differenza.
In sintesi
- Docs as code significa documentazione in file di testo, gestita con Git e rivista prima di pubblicarla.
- La documentazione cambia nella stessa richiesta della cosa documentata, e resta aggiornata.
- Dividere i contenuti in tutorial, guide, riferimento e spiegazioni rende le pagine più utili.
- MkDocs è il punto di partenza più semplice; Sphinx è adatto a progetti software estesi.
- Controlli automatici su link, formattazione e stile mantengono la qualità senza fatica.
