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.
:::
La documentazione è strutturata in quattro pilastri fondamentali per coprire l'intero ciclo di vita del software.
Come generare documentazione tecnica direttamente dai commenti nel codice sorgente.
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.
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).
Le basi della scrittura tecnica.
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
- Automazione: Se può essere generato dal codice, non scriverlo a mano.
- Vicinanza: La documentazione tecnica deve risiedere il più vicino possibile al codice (nello stesso repository).
- Verificabilità: Gli esempi di codice nella documentazione devono essere testati (DocTests).
- Essenzialità: Meglio una pagina breve e aggiornata che dieci pagine lunghe e obsolete.
- Targeting: Scrivi sapendo chi leggerà (Utente vs Sviluppatore vs Manutentore).
o!