Documentazione senza scriverla a mano 📖
TL;DR: La documentazione generata da un agente è veloce da produrre, ma ogni affermazione deve essere verificata. La doc sbagliata è peggio di nessuna doc perché qualcuno la leggerà e ci farà affidamento. Il trucco non è generare di meno, ma verificare di più.
Il problem della documentazione 📝
La documentazione è quella cosa che tutti sanno essere importante e nessuno vuole fare. È noiosa, si obsoleta rapidamente, e il rapporto costo/beneficio sembra sempre sfavorevole. Poi arriva un agente di coding e dice: “posso generarla per te.” Ed è vero — può farlo. Ma c’è un problema sottile.
Una documentazione giusta è utilissima. Una documentazione sbagliata è peggio di nessuna documentazione, perché qualcuno la leggerà, la crederà, e prenderà decisioni basate su informazioni false. E il bello è che la doc sbagliata sembra giusta — è scritta con lo stesso tono, lo stesso formato, la stessa struttura della doc vera. Solo che dice cose che non corrispondono al codice.
Il rischio non è avere poca documentazione. Il rischio è avere documentazione che sembra affidabile ma non lo è.
Cosa può fare l’agente 🤖
Un agente di coding è eccellente per:
- Generare README — descrizione del progetto, installazione, usage, contribuzione.
- Documentare API — estrarre firme, parametri, tipi di ritorno dal codice.
- Creare ADR — documentare decisioni architetturali e il loro contesto.
- Produrre changelog — riepilogo delle modifiche tra versioni.
- Scrivere guide di contribuzione — come contribuire, standard, processo di review.
Il punto è che l’agente estrae dal codice, non inventa. Ma a volte l’estrazione è imperfettae l’agente può interpretare male un pattern, extrapolare un comportamento che non esiste, o semplificare un flusso complesso.
La verifica come competenza 🔍
La parte difficile non è generare la documentazione. È verificarla. E la verifica richiede competenza: devi capire il codice abbastanza bene da sapere se la documentazione lo descrive correttamente.
Alcune regole concrete:
- Ogni affermazione deve essere verificabile — se la doc dice “l’endpoint accetta un parametro
iddi tipostring”, verifica che sia davvero così. - Confronta con il codice reale — non con ciò che “dovrebbe” essere.
- Verifica gli edge case — la doc menziona tutti gli errori possibili? Tutti i comportamenti?
- Aggiorna la doc quando il codice cambia — la documentazione vive con il codice, non è un’appendice.
In Documentazione da codebase approfondiamo il workflow completo: dalla scelta del formato alla verifica di coerenza, dalla doc-as-code all’aggiornamento continuo.
Doc-as-code: la strada giusta 📚
Il concetto di doc-as-code è semplice: la documentazione vive nel repository insieme al codice. È versionata, revisionabile, parte del CI. Non è un Wiki dimenticato, non è un Google Drive perso: è un file che evolve con il progetto.
Questo significa:
- Stesso repo, stesso branch — la doc è vicina al codice che documenta.
- Stesso processo di review — la doc passa dalla PR come il codice.
- Stessa automazione — la doc è testata (almeno per coerenza) insieme al codice.
La documentazione non è un extra: è una componente architetturale. Trattala come tratti il codice.
Il paradosso della doc generata 🎯
Ecco il paradosso: più la documentazione è facile da generare, più diventa critico verificarla. Prima, quando scrivere doc richiedeva un’ora, chi la scriveva la conosceva per forza. Oggi, quando un agente la genera in 30 secondi, chi la verifica potrebbe non averla mai letta.
La soluzione non è generare meno. È verificare di più. Ogni riga di documentazione generata dovrebbe essere letta da qualcuno che conosce il codice. Non è un costo: è un investimento nella credibilità della serie.
E forse la lezione più semplice: la documentazione non è un atto di generazione. È un atto di verifica. L’agente scrive, tu verifichi. L’agente estrae, tu confermi. L’agente produce, tu certifichi. Solo allora la documentazione è affidabile. Solo allora vale la pena di esistere.