Principio: "Documentation is UI for the brain. Make it intuitive."
::: info
La scrittura tecnica non è letteratura; è ingegneria della comunicazione. L'obiettivo è trasferire informazioni dal cervello dello scrittore a quello del lettore con il minimo sforzo cognitivo e la massima precisione.
:::
Utilizziamo il GitHub Flavored Markdown (GFM) con le estensioni specifiche di Wiki.js per creare gerarchie visive chiare.
Usa i blocchi di avviso per evidenziare informazioni critiche senza interrompere il flusso del testo:
::: info: Per note di contesto o suggerimenti.::: tip: Per "pro-tips" di ottimizzazione.::: warning: Per avvisare di potenziali rischi hardware/software.::: danger: Per procedure distruttive (es. rm -rf, wipe di dischi).
Le tabelle devono essere usate per confronti tecnici o parametri di configurazione. Le task list per i workflow di installazione.
Per organizzare la struttura delle pagine, adottiamo il framework Diátaxis, che divide la documentazione in 4 tipologie distinte:
- Tutorials (Learning-oriented): Guide passo-passo per principianti (es. "Il tuo primo script Python").
- How-to Guides (Problem-oriented): Soluzioni a problemi specifici (es. "Come configurare BitLocker via CLI").
- Reference (Information-oriented): Descrizioni tecniche pure (es. "Parametri della funzione
process_data()").
- Explanation (Understanding-oriented): Approfondimenti teorici e architetturali (es. "Perché usiamo Proxmox invece di ESXi").
graph TD
DOC[Documentation Hub] --> LEARN[Tutorials: Learning]
DOC --> PROB[How-to: Problem Solving]
DOC --> INFO[Reference: Facts]
DOC --> THEO[Explanation: Concepts]
style LEARN fill:#bbf,stroke:#333
style PROB fill:#bfb,stroke:#333
style INFO fill:#fbb,stroke:#333
style THEO fill:#fdb,stroke:#333
In qualità di ingegneri, applichiamo queste regole per eliminare l'ambiguità:
- Usa la Voce Attiva:
- ❌ Bad: "Il comando deve essere eseguito dall'utente."
- ✅ Good: "Esegui il comando."
- Sii Conciso (Omit Needless Words): Elimina avverbi e aggettivi inutili. La precisione tecnica non ha bisogno di ornamenti.
- Una sola idea per frase: Se una frase contiene "e", "ma", "mentre", valuta di dividerla in due.
- Usa Liste Puntate: Se devi elencare più di due elementi, usa una lista. Migliora drasticamente la scansione visiva.
- Terminologia Consistente: Se chiami un componente "Proxy", non chiamarlo "Gateway" nella pagina successiva.
Proprio come facciamo il linting del codice Python (Pylint/Flake8), dobbiamo fare il linting della documentazione.
- Markdownlint: Estensione VS Code per garantire che il Markdown sia formattato correttamente.
- Vale: Un linter di stile che può verificare il rispetto di regole grammaticali e di stile (es. Google o Microsoft Style Guide).
- Spell Check: Obbligatorio prima di ogni commit/salvataggio sul Wiki.
::: tip
Tratta la documentazione come codice:
- Versionamento: Mantieni i file Markdown nel repository Git insieme al codice.
- Review: Sottoponi le modifiche alla documentazione a Peer Review.
- Automazione: Usa tool come Pandoc per convertire il Markdown in PDF o DOCX se devi produrre report formali per esterni.
:::
Ultimo aggiornamento: {{UPDATE_DATE}} | Tags: #TechnicalWriting #Markdown #Diataxis #DocumentationStyle