📚 Documentation as Code: AI-Driven Governance

Assioma: “Code explains the HOW; Documentation explains the WHY. AI synchronizes BOTH.”

::: info OBIETTIVO Automatizzare la stesura e il mantenimento della documentazione tecnica. Utilizzeremo l’IA per generare docstrings professionali e integreremo strumenti di build (Sphinx per Python, Doxygen per C++) per produrre siti web di documentazione che si aggiornano ad ogni modifica del codice. :::

1. Il Paradigma “Scribe”

In questo workflow, l’ingegnere scrive la logica, mentre l’IA (lo Scribe) si occupa della forma documentale.

Strategia di Prompting per lo Scribe

Non chiedere “scrivimi i commenti”. Chiedi conformità agli standard:

• Python: “Agisci come un Senior Python Developer. Genera docstrings conformi al Google Style (PEP 257). Includi sezioni Args, Returns e Raises.”
• C++: “Genera commenti compatibili con Doxygen in stile Javadoc. Spiega i vincoli di thread-safety e la gestione della memoria (ownership) degli argomenti.”

2. Automazione per Python (Sphinx)

Sphinx è lo standard per l’ecosistema Python. Grazie all’estensione autodoc, legge le docstrings generate dall’IA e le trasforma in un portale web.

Workflow Operativo:

1. Generazione: Usa Copilot Edits per popolare i file .py con docstrings.
2. Build: Esegui Sphinx per generare l’HTML.
3. Verify: Controlla che le descrizioni riflettano correttamente la logica modificata.

3. Automazione per C++ (Doxygen)

Doxygen è indispensabile per visualizzare graficamente le gerarchie di classi e i grafi di chiamata nel codice C++.

Integrazione IA:

Chiedi a Claude/GPT di analizzare un file .hpp e aggiungere i tag @brief, @param, @return e @note. L’IA è particolarmente brava a identificare possibili eccezioni (@exception) che lo sviluppatore potrebbe aver omesso.

📉 Workflow della Documentazione (Mermaid 8.8.2)

graph TD
    A["Codice Sorgente (.py / .cpp)"] --> B["AI Agent: Docstring Generator"]
    B --> C["Codice Documentato (Git Commit)"]
    
    subgraph Build_Pipeline
        C --> D{"Tipo Progetto?"}
        D -->|Python| E["Sphinx Build"]
        D -->|C++| F["Doxygen Build"]
    end
    
    E --> G["Portale Documentazione (HTML)"]
    F --> G
    
    G --> H["Wiki.js Integration / Static Hosting"]

4. CI/CD: Il Guardiano della Documentazione

Per un progetto di grado enterprise, la documentazione deve essere un “gate” della pipeline:

• Doc-Linting: Usa tool come interrogate (Python) per verificare che la percentuale di codice documentato non scenda sotto una certa soglia (es. 80%).
• Auto-Update: Configura una GitHub Action che esegua il build della documentazione e la pubblichi automaticamente dopo ogni merge nel branch main.

5. Esempio di automazione nella documentazione

• Documentation as Code: Il Protocollo LV_Sync_Doc Uno strumento di automazione progettato per sincronizzare istantaneamente il codice sorgente con la documentazione narrativa, il log delle modifiche e i manuali utente bilingue.

💡 Note dell’Architetto: “The Golden Rule”

L’IA non deve solo descrivere cosa fa il codice (lo leggiamo già dal codice), ma deve spiegare l’intento.

• ❌ Cattiva documentazione: def add(a, b): # Aggiunge a e b
• ✅ Buona documentazione (AI-Enhanced): def add(a, b): # Implementa l'algoritmo di somma per il calcolo del budget fiscale, gestendo l'arrotondamento secondo la norma ISO-XXX.

Tags: #DocumentationAsCode #Sphinx #Doxygen #AI #TechnicalWriting #Governance*