Documentazione tecnica generata da AI: linee guida per non farla diventare spam

Il problema che nessuno ammette

Un team di 8 sviluppatori, deadline stretta, nessuno vuole scrivere i README. Soluzione ovvia: si passa tutto a GPT-4 e in venti minuti la repo ha la sua documentazione. Aspetta — quella documentazione descrive un'API con endpoint che non esistono più, parametri rinominati tre sprint fa e un esempio curl che restituisce 401 dal giorno uno.

Non è un caso inventato. È la situazione media che troviamo quando facciamo onboarding su codebase di clienti che hanno adottato la generazione AI della documentazione senza un processo di validazione. Il risultato: documentazione abbondante, inutilizzabile e — peggio — fuorviante.

Perché la documentazione AI degenera in spam

Un LLM genera testo plausibile, non testo corretto. La distinzione è sottile ma devastante nel contesto tecnico.

Problema 1: il modello non conosce il contesto runtime. Se gli passi solo il codice sorgente di una funzione, il modello non sa che quella funzione è invocata solo in un contesto autenticato, che il parametro userId viene validato a monte, che l'eccezione che lancia viene swallowata dal middleware. Genera documentazione che sembra completa ma manca dei vincoli impliciti più importanti.

Problema 2: il drift temporale è immediato. Il codice cambia. La documentazione generata non si aggiorna da sola. Dopo due sprint, quella doc è già obsoleta. La squadra lo sa, smette di leggerla, smette di aggiornarla. Diventa decorazione.

Problema 3: la generazione in bulk produce uniformità falsa. Quando generi documentazione per 200 funzioni in batch, il tono è identico, la struttura è identica, le descrizioni si assomigliano troppo. Il cervello umano smette di leggere testo prevedibile. Nessuno legge quella documentazione, nemmeno chi l'ha generata.

Il processo che funziona

La generazione AI è uno strumento di scaffolding, non di delivery. Trattarla diversamente produce i problemi descritti sopra.

1. Genera solo su input strutturato

Non passare al modello il file sorgente grezzo e chiedergli "documentami questa funzione". Costruisci un prompt che include:

Funzione: {{nome_funzione}}
Firma: {{signature}}
Contesto di invocazione: {{dove_viene_chiamata}}
Vincoli noti: {{precondizioni, side effect, limitazioni}}
Esempio di input reale (anonimizzato): {{esempio}}
Esempio di output atteso: {{esempio}}
Formato richiesto: JSDoc / OpenAPI / Markdown con sezione Parameters, Returns, Throws, Example

Se non riesci a riempire il campo "Vincoli noti", non generare ancora. Vai a leggerti il codice.

2. Separa generazione da revisione: ruoli distinti

La persona che genera non è la persona che approva. Non perché non si fidi di sé stessa, ma perché il cervello umano che ha scritto il prompt ha già un modello mentale del comportamento atteso — non vedrà le imprecisioni. Serve un secondo paio di occhi, preferibilmente di chi dovrà effettivamente usare quella documentazione.

Nel workflow pratico:

Dev A → genera bozza con LLM → PR con label "doc/ai-generated"
Dev B (non autore del codice) → revisione tecnica → approva o richiede correzioni
Tech lead → merge solo dopo che i test di integrazione sono verdi

La label doc/ai-generated non è opzionale. Serve al team per calibrare il livello di scrutinio e per tracciare nel tempo la qualità media della generazione AI.

3. Testa gli esempi di codice

Ogni snippet nella documentazione deve girare. Non c'è altra regola.

Se usi GitHub Actions:

jobs:
  test-doc-examples:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Estrai snippet dalla documentazione
        run: python scripts/extract_doc_snippets.py --output ./snippets
      - name: Esegui snippet
        run: bash scripts/run_snippets.sh ./snippets

Uno script che estrae i blocchi di codice dai file Markdown e li esegue in un ambiente isolato. Se falliscono, la PR non viene mergiata. Semplice, non elegante, funzionante.

4. Versiona la documentazione insieme al codice

La documentazione vive nella stessa repo del codice. Non su Confluence, non su Notion, non su un wiki esterno che nessuno aggiorna. Ogni commit che modifica una funzione pubblica triggera un check che verifica se il file di documentazione corrispondente è stato toccato. Se non lo è, il check fallisce con un warning.

# scripts/check_doc_sync.py
import subprocess, sys

changed = subprocess.check_output(
    ["git", "diff", "--name-only", "HEAD~1"]
).decode().splitlines()

src_files = [f for f in changed if f.startswith("src/") and f.endswith(".py")]
doc_files = [f for f in changed if f.startswith("docs/")]

if src_files and not doc_files:
    print("WARNING: modifiche a src/ senza aggiornamenti in docs/")
    sys.exit(1)

Non è un sistema infallibile — un dev può aggiornare un file doc con una riga vuota e far passare il check — ma abbassa la probabilità di drift non intenzionale.

5. Stabilisci una metrica di obsolescenza

Ogni documento ha una data di ultima validazione. Se quella data supera una soglia (es. 90 giorni per API pubbliche, 180 per moduli interni), il documento entra in uno stato "needs-review" e viene escluso dai risultati della ricerca interna.

Non stai cancellando documentazione vecchia. Stai etichettando onestamente cosa è stato verificato di recente e cosa no.

Take-away operativo

La documentazione AI funziona se la tratti come codice: input strutturato, revisione separata, test degli esempi, versionamento nel repo, scadenza esplicita. Se invece la usi come strumento di produzione in bulk senza questi controlli, ottieni volume senza valore — e il tuo team imparerà molto in fretta a ignorarla.

Le ore risparmiate nella generazione vengono spese dieci volte in debug causato da documentazione sbagliata. Il ROI reale lo vedi solo se il processo di validazione regge.

---

Evviva Group supporta team di sviluppo che vogliono integrare strumenti AI nel workflow tecnico senza perdere qualità. Se stai strutturando questo processo, possiamo aiutarti.