✍️ Narrative Formats & Technical Writing Standards

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. :::

1. Markdown Avanzato (Wiki.js & GFM)

Utilizziamo il GitHub Flavored Markdown (GFM) con le estensioni specifiche di Wiki.js per creare gerarchie visive chiare.

Componenti di Segnalazione (Callouts)

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).

Tabelle e Task Lists

Le tabelle devono essere usate per confronti tecnici o parametri di configurazione. Le task list per i workflow di installazione.

• Configurazione Ambiente
• Deploy Produzione

2. Il Framework Diátaxis

Per organizzare la struttura delle pagine, adottiamo il framework Diátaxis, che divide la documentazione in 4 tipologie distinte:

1. Tutorials (Learning-oriented): Guide passo-passo per principianti (es. “Il tuo primo script Python”).
2. How-to Guides (Problem-oriented): Soluzioni a problemi specifici (es. “Come configurare BitLocker via CLI”).
3. Reference (Information-oriented): Descrizioni tecniche pure (es. “Parametri della funzione process_data()”).
4. Explanation (Understanding-oriented): Approfondimenti teorici e architetturali (es. “Perché usiamo Proxmox invece di ESXi”).

📉 Mappa Concettuale Diátaxis (Mermaid)

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

3. Regole d’Oro del Technical Writing

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.

4. Documentation Quality Control (Linting)

Proprio come facciamo il linting del codice Python (Pylint/Flake8), dobbiamo fare il linting della documentazione.

1. Markdownlint: Estensione VS Code per garantire che il Markdown sia formattato correttamente.
2. Vale: Un linter di stile che può verificare il rispetto di regole grammaticali e di stile (es. Google o Microsoft Style Guide).
3. Spell Check: Obbligatorio prima di ogni commit/salvataggio sul Wiki.

💡 Engineering Tips

::: tip Tratta la documentazione come codice:

1. Versionamento: Mantieni i file Markdown nel repository Git insieme al codice.
2. Review: Sottoponi le modifiche alla documentazione a Peer Review.
3. 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