Ti è mai capitato di cercare una ricetta online, per poi replicarla? Quello è un esempio semplice di stesura di un manuale d’uso, che spiega come raggiungere un certo risultato svolgendo specifiche azioni.

Oggi ti fornisco alcuni consigli su come scrivere un manuale d’uso per ricette, prodotti o software. La complessità non incide sulla metodologia impiegabile, ma solo sulla lunghezza della ramificazione del manuale.

Per la stesura di un manuale, il primo passo che consiglio è quello di studiare il metodo DITA (Darwin Information Typing Architecture), uno standard XML per la creazione e gestione di documentazione tecnica, progettato per facilitare la creazione, l’organizzazione e la pubblicazione di contenuti.

Non fissiamoci sull’aspetto tecnico dell’XML, ma focalizziamoci su ciò che dai manuali di DITA possiamo apprendere e replicare, banalmente, su qualsivoglia programma, anche su un foglio di carta.

Il primo insegnamento che ci lascia DITA è di suddividere la struttura di un manuale per argomenti, ciascuno dei quali sarà suddiviso in argomenti più piccoli e così via. Ciascun argomento deve essere poter avere senso anche se preso individualmente, e può essere, tendenzialmente, di 3 tipologie:

• Concept (concetto che spiega o introduce l’argomento)
• Task (i passaggi per svolgere un’azione inerente all’argomento)
• Reference (i riferimenti contenuti nelle argomentazioni, ad esempio i comandi che usiamo nello svolgere una determinata task)

Con questa semplice infarinatura, possiamo già costruire la struttura di un manuale d’uso, il passo più importante. 

Introdotto il mondo DITA, possiamo ora abbozzare la stesura di un manuale d’uso. Per comodità, e senza alcuna pretesa, usiamo come oggetto del nostro manuale il programma Word, noto a tutti.

La mappatura di un manuale d’uso

Come anticipato, il manuale d’uso è un insieme di argomenti che devono esistere singolarmente, ma comunque collegati l’uno con l’altro. L’intento finale è di fornire all’utente tutte le informazioni per procedere, in maniera lineare, allo svolgimento delle funzioni che desidera.

Per cui, la priorità è l’organizzazione dei contenuti, cioè la mappatura del manuale d’uso. Di seguito un esempio.

 – Word (Concept padre)

 – – Nuovi file word (Concept figlio 1)

 – – – Cos’è un nuovo file word (Concept figlio del figlio 1)

 – – – Creare un nuovo file word (Task figlio del figlio 1)

 – – – I bottoni presenti su word (Reference figlio del figlio 1)

 – – Le immagini su word (Concept figlio 2)

 – – – Cos’è un’immagine su word (Concept figlio del figlio 2)

 – – – Inserire un’immagine su word (Task figlio del figlio 2)

 – – – I bottoni per la creazione di immagini (Reference figlio del figlio 2)

E così via, possiamo proseguire con l’alberatura fino a quando non termineremo gli argomenti.

La scrittura di un argomento (topic) del manuale d’uso

Definita l’alberatura dei contenuti del manuale d’uso, adesso bisogna creare un argomento – topic – per ciascuno dei punti dell’elenco precedente. Chiaramente il risultato cambierà in funzione della tipologia di argomento.

La scrittura di un argomento concept del manuale d’uso

Nella scrittura di un argomento concept, come ad esempio “Cos’è un nuovo file word”, dobbiamo semplicemente spiegare di cosa si tratta.

Il risultato finale potrebbe essere il seguente: un nuovo file Word è un tipo di documento digitale creato e modificabile con Microsoft Word, che fa parte della suite di software Microsoft Office, da zero. Questi file hanno generalmente l’estensione “.doc” o “.docx”.

In alcuni casi potrà risultare banale, ma rende completo il manuale e contestualizza sempre i passaggi successivi, di solito un argomento task (compito).

La scrittura di un argomento task del manuale d’uso

Nella scrittura di un argomento task, come ad esempio “Creare un nuovo file word”, spieghiamo come effettivamente si possa compiere l’azione, senza dare nessun passaggio per scontato.

Questo approccio è quello che adotto per tutti i manuali presenti su questo sito e per i manuali che scrivo per conto dei clienti.

La scrittura di un argomento reference del manuale d’uso

L’argomento reference è una tipologia di topic che semplifica la comprensione dei passaggi precedente. Ad esempio, per creare un nuovo file word potrei scrivere in uno step: Cliccare su File.

Nell’argomento reference, in forma tabellare, affiancherò ai termini tecnici, come quelli dei bottoni impiegati, la spiegazione. Per File potrei scrivere che si tratta del bottone in alto a sinistra all’interno di un file word.

Questa breve introduzione non è chiaramente esaustiva o rigida nella sua interpretazione, ma se dovessi essere interessato ad approfondire, sia da un punto di vista architetturale che da un punto di vista tecnico (esiste un programma, Oxygen Author, che consente di scrivere in .dita, un formato di file), ti consiglio di acquistare il libro di DITA.