Creare un manuale¶

Una volta che l'infrastruttura è configurata, aggiungere un nuovo manuale al sito è un processo strutturato ma semplice. Questo capitolo descrive il ciclo di lavoro per passare da un'idea (o da materiali esistenti) a un manuale pubblicato.

Partire dai materiali¶

Un nuovo manuale può nascere da situazioni diverse:

Da documenti esistenti: PDF, Word, presentazioni PowerPoint che contengono già il contenuto da trasformare. Il lavoro è principalmente di conversione e riorganizzazione.

Da contenuti web: pagine già pubblicate altrove che si vogliono consolidare in un formato più strutturato.

Da zero: un argomento da documentare senza materiali preesistenti. Il lavoro include la creazione dei contenuti.

In tutti i casi, il primo passo è definire la struttura.

Definire la struttura¶

Prima di scrivere, è utile progettare l'architettura dei contenuti. La domanda guida è: come organizzo le informazioni perché siano trovabili e comprensibili?

La struttura a tre livelli di MkDocs Material offre una griglia:

Livello 1 (Sezioni principali): le macro-aree dell'argomento. Per un manuale software potrebbero essere "Iniziare", "Funzionalità", "Riferimenti". Per un corso: "Modulo 1", "Modulo 2", ecc.

Livello 2 (Capitoli): gli argomenti specifici dentro ogni sezione. Ogni capitolo diventa un file Markdown e una voce nella sidebar.

Livello 3 (Sottosezioni): i paragrafi interni a ogni capitolo. Sono i titoli H2 e H3 nel Markdown, navigabili dalla table of contents.

Una buona struttura emerge dall'incrocio tra la logica del contenuto e le esigenze del lettore. Non esiste una formula unica.

Creare i file¶

Per ogni manuale, crea una cartella in docs/:

docs/
├── index.md
├── nuovo-manuale/
│   ├── index.md          # Introduzione al manuale
│   ├── capitolo-1.md
│   ├── capitolo-2.md
│   └── capitolo-3.md
└── ...

L'index.md dentro la cartella del manuale serve come pagina di ingresso: presenta l'argomento, il pubblico target, cosa troverà il lettore.

I nomi dei file dovrebbero essere: - Lowercase - Senza spazi (usa trattini) - Senza caratteri speciali o accentati - Descrittivi ma brevi

Aggiornare la navigazione¶

Ogni nuovo manuale va aggiunto in mkdocs.yml, nella sezione nav::

nav:
  - Home: index.md
  - Nuovo Manuale:
    - nuovo-manuale/index.md
    - Capitolo 1: nuovo-manuale/capitolo-1.md
    - Capitolo 2: nuovo-manuale/capitolo-2.md
    - Capitolo 3: nuovo-manuale/capitolo-3.md

L'ordine nel file determina l'ordine nella navigazione. La struttura indentata riflette la gerarchia: le voci sotto "Nuovo Manuale" appariranno come sottomenu.

Aggiornare la home page¶

La home page del sito (docs/index.md) dovrebbe elencare i manuali disponibili. Quando aggiungi un manuale, aggiungi anche un link e una breve descrizione nella home.

Scrivere i contenuti¶

Con la struttura definita, la scrittura può procedere capitolo per capitolo. Alcuni principi utili:

Paragrafi brevi: sul web si legge diversamente che su carta. Paragrafi di 3-5 righe sono più digeribili di blocchi densi.

Un concetto per sezione: ogni titolo H2 o H3 dovrebbe corrispondere a un'idea. Se una sezione copre troppi concetti, probabilmente va divisa.

Usare i callout: le note, gli avvisi, i suggerimenti spezzano il flusso e attirano l'attenzione sui punti importanti.

Link interni: collega i capitoli tra loro quando fanno riferimento a concetti spiegati altrove. In Markdown: [testo del link](../altro-capitolo.md).

Convertire materiali esistenti¶

Se parti da documenti esistenti, Pandoc può aiutare nella conversione:

pandoc documento.docx -o output.md --wrap=none

Il risultato richiede quasi sempre revisione: la struttura dei titoli potrebbe non corrispondere a quella desiderata, le immagini vanno estratte e ri-collegate, la formattazione va adattata.

Per PDF, la conversione diretta è più problematica. Spesso conviene partire dal testo estratto e ristrutturarlo manualmente.

Pubblicare¶

Con i file creati e la navigazione aggiornata:

1. Commit delle modifiche su GitHub
2. Il workflow parte automaticamente
3. In 2-3 minuti il manuale è online

Per manuali corposi, può essere utile pubblicare progressivamente: prima la struttura con contenuti parziali, poi i capitoli completi uno alla volta. Questo permette di verificare che la navigazione funzioni prima di investire nella scrittura completa.

Iterare¶

La pubblicazione non è la fine. Il vantaggio di questo sistema è la facilità di aggiornamento. Errori, integrazioni, chiarimenti possono essere aggiunti in qualsiasi momento.

Una pratica utile: rileggere il manuale dopo qualche giorno dalla prima pubblicazione, con occhi freschi. Spesso emergono passaggi poco chiari o mancanze che non si notavano durante la scrittura.