📝 Software Documentation Engineering

Filosofia: “Code explains HOW, Documentation explains WHY.”

::: info Questa sezione definisce gli standard e le metodologie per la redazione della documentazione tecnica. L’obiettivo è produrre materiale che sia auto-aggiornante (ove possibile), preciso e manutenibile, seguendo i principi della Documentation as Code. :::

📑 Indice dei Moduli

La documentazione è strutturata in quattro pilastri fondamentali per coprire l’intero ciclo di vita del software.

⚙️ 1. In-Code Documentation (Auto-gen)

Come generare documentazione tecnica direttamente dai commenti nel codice sorgente.

• Doxygen per C++: Standard per l’estrazione di grafi di chiamata e reference delle classi.
• Sphinx & Docstrings per Python: Utilizzo di reStructuredText e Google Style per documentare librerie e moduli.

🏗️ 2. Architectural Modeling (UML & Flow)

Rappresentazione visuale della logica e dell’infrastruttura.

• UML & Mermaid.js: Diagrammi di sequenza, di classe e di stato integrati nel Markdown.
• C4 Model: Tecnica di diagrammazione a livelli per architetture software complesse.

🌐 3. API & Protocol Documentation

Standard per la documentazione di interfacce di comunicazione.

• OpenAPI (Swagger): Documentazione interattiva per REST API (FastAPI/Flask).
• AsyncAPI: Standard per sistemi ad eventi (MQTT/Websockets).

✍️ 4. Formati e Standard Narrativi

Le basi della scrittura tecnica.

• Markdown Avanzato: Estensioni, tabelle e best practices per Wiki.js.
• Technical Writing Principles: Regole per scrivere guide “prooff-proof”, chiare e senza ambiguità.

📉 Il Ciclo della Documentazione (Mermaid)

graph LR
    CODE[Scrittura Codice + Comments] --> BUILD{CI/CD Pipeline}
    BUILD --> DOX[Generazione Doxygen/Sphinx]
    BUILD --> TEST[Validazione Esempi]
    DOX --> PUBLISH[Pubblicazione su Wiki/Web]
    PUBLISH --> FEEDBACK[Revisione e Update]
    FEEDBACK --> CODE

🏆 I 5 Comandamenti della Documentazione Professionale

1. Automazione: Se può essere generato dal codice, non scriverlo a mano.
2. Vicinanza: La documentazione tecnica deve risiedere il più vicino possibile al codice (nello stesso repository).
3. Verificabilità: Gli esempi di codice nella documentazione devono essere testati (DocTests).
4. Essenzialità: Meglio una pagina breve e aggiornata che dieci pagine lunghe e obsolete.
5. Targeting: Scrivi sapendo chi leggerà (Utente vs Sviluppatore vs Manutentore).

o!