Come scrivere un manuale utente

1. Sottovalutare l’importanza del manuale utente

Il primo errore che compie spesso chi deve scrivere un manuale utente o un manuale d’uso e manutenzione di una macchina non riguarda tanto il contenuto, ma l’atteggiamento. C’è chi lo considera una seccatura, perché comporta lavoro e costi aggiuntivi e c’è chi lo ritiene superfluo perché “tanto nessuno lo legge”.

Quanto sono giustificati questi atteggiamenti?

È vero che la preparazione di un manuale d’uso e manutenzione richiede tempo e risorse, ed è vero anche che non sempre l’utente legge le istruzioni dalla prima all’ultima parola. Bisogna ricordare però che, secondo la direttiva 2006/42/CE, conosciuta anche come “direttiva macchine”, il manuale è una parte integrante del prodotto e non un componente facoltativo o accessorio. È un requisito per essere conformi alle prescrizioni di legge.

La tutela dal punto di vista legale non deve essere, però, l’unico motivo che spinge un’azienda a curare i contenuti del manuale che accompagna i suoi prodotti.

Se le informazioni e le istruzioni sono riportate in modo chiaro e comprensibile, si riducono le richieste di chiarimento e i reclami, diminuiscono i rischi per l’utente, i danni e il malfunzionamento. Di conseguenza si abbassano i costi legati all’assistenza clienti, alle sostituzioni e agli interventi in campo.

2. Usare un linguaggio inutilmente complesso

Uno degli errori più comuni riguarda la scelta delle parole e dei termini. Qual è la differenza tra i due? Le parole appartengono al lessico comune, quello che usiamo abitualmente, mentre i termini appartengono al lessico specializzato, che è proprio di un prodotto e del settore al quale appartiene.

L’errore più comune consiste nel pensare che, se l’argomento è complesso, non siano adatte espressioni semplici. In realtà, proprio perché i manuali trattano spesso argomenti complicati, è importante preferire un linguaggio comprensibile a tutti.

Per quanto possa sembrare un consiglio banale, una risorsa utile in questo senso è il Vocabolario di base della lingua italiana, un dizionario di italiano che raccoglie le parole più usate e comprese dalla maggioranza dei parlanti.

Ad esempio, invece di “visionare” che non è registrato nel vocabolario, si possono utilizzare “controllare” o “esaminare”.

Oltre alle parole che appartengono a un registro più alto, sono frequenti le espressioni cristallizzate, alle quali ricorriamo spesso per abitudine. “Praticare un foro” o “effettuare un taglio” possono essere sostituite con “forare” e “tagliare” che sono più brevi e dirette.

Come va gestita, invece, la terminologia?

Prima di tutto bisogna chiedersi a chi è destinato il manuale. Si rivolge a un utente esperto, ad esempio a un installatore, o a un utente generico? In questo caso va spiegato il significato dei termini. Per aiutare gli utenti meno esperti, si può creare un glossario, cioè una lista dei termini con la loro spiegazione.

Il glossario può andare da una semplice raccolta di termini accompagnata da una breve definizione, fino a una vera e propria banca dati terminologica, in cui ogni concetto è spiegato, illustrato con disegni o fotografie ed eventualmente tradotto in tutte le lingue necessarie.

3. Usare sinonimi non necessari

Contrariamente a quanto si possa pensare, e a quanto ci hanno insegnato a scuola, l’uso dei sinonimi è uno degli errori più comuni. “Dispositivo”, “strumento”, “apparecchio”, “congegno”, “macchina”, “macchinario”, oppure “tasto”, “pulsante” e “bottone” sono spesso usati per evitare le ripetizioni.

Mentre in un post o in un tema i sinonimi arricchiscono il testo, in un documento tecnico creano ambiguità. Se le istruzioni prevedono l’uso della “chiave a brugola”, questa chiave va chiamata così in tutto il documento, senza usare “utensile” e, nella frase successiva, “attrezzo”, perché l’utente potrebbe non capire a che cosa ci si sta riferendo.

Prendiamo come esempio queste frasi:

In poche righe si usano “giubbetto equilibratore”, “equilibratore” e “gav”: tre modi per riferirsi allo stesso prodotto. Quando esistono più termini per indicare un oggetto, anche se sono tutti corretti, bisogna sceglierne uno e usarlo lungo tutto il testo.

4. Usare linguaggio gergale o abbreviature tecniche senza spiegazione

Un altro errore da evitare è l’uso di linguaggio gergale o di abbreviature tecniche date senza alcuna spiegazione. È importante usare la terminologia ufficiale. “Fischer” e “Forbox”, ad esempio, indicano la marca e non il prodotto. Andrebbero sostituiti con “tassello” e “morsetto”.

Vanno evitate le espressioni gergali: si può dire “remotizzabile” parlando con i colleghi, ma in un manuale è più corretto scrivere “può essere collegato in remoto”, che per quanto più lungo è immediatamente comprensibile.

Nell’esempio citato nella sezione precedente è presente un’abbreviazione: “gav”. Nel linguaggio tecnico si usano spesso forme abbreviate, come sigle o acronimi. Sono utili perché fanno risparmiare spazio e velocizzano la lettura, ma devono essere utilizzati con coerenza.

Se un redattore tecnico decide di usare un’abbreviazione, ne dovrebbe spiegare il significato la prima volta che compare e poi usarla in tutto il documento.

Ad esempio: “Il giubbetto ad assetto variabile (da qui in poi GAV)”.

Attenzione! L’abbreviazione va scritta sempre nello stesso modo: non riportare “GAV” e poi “gav”. Inoltre, se il manuale contiene molte abbreviazioni, è utile crearne una lista che le raccoglie e ne spiega il significato. L’utente potrà consultarla in caso di dubbio.

5. Usare uno stile ridondante

La tabella riporta gli errori più ricorrenti e i suggerimenti per scrivere frasi più dirette e comprensibili.

Regola	Forma da evitare	Forma consigliata
Usa la forma attiva, non quella passiva.	Il cavo dell’antenna deve essere collegato allo spinotto.	Collegare il cavo dell’antenna allo spinotto.
	Il software viene utilizzato per controllare gli spostamenti della macchina.	Il software controlla gli spostamenti della macchina.
Preferisci l’indicativo a modi verbali complessi come il congiuntivo e il condizionale.	Qualora l’apparecchio presentasse difetti di fabbricazione, contatta l’assistenza clienti.	Se l’apparecchio presenta difetti di fabbricazione, contatta l’assistenza clienti.
Sostituisci le forme nominali con le forme verbali.	L’utente ha la possibilità di avvalersi del diritto di recesso.	L’utente può rendere il prodotto.
Usa espressioni dirette.	Evitare di far cadere lo strumento.	Non far cadere lo strumento.
Scegli espressioni brevi.	è in grado di trasmettere provvede a controllare	trasmette controlla

6. Scrivere le unità di misura nel modo scorretto

Le unità di misura sono tra gli elementi più frequenti nei manuali tecnici, ma c’è molta confusione sul modo corretto di scriverle. Ad esempio, non è corretto scrivere:

Le forme corrette sono:

Ovvero, ci vuole uno spazio fra il numero e l’unità di misura e l’unità di misura va scritta secondo il relativo standard internazionale.

In caso di dubbio puoi consultare il Sistema internazionale di unità di misura, conosciuto anche come SI, che raccoglie le norme per la scrittura delle unità di misura e dei relativi simboli.

7. Non adattare le cifre al mercato di destinazione

Numeri e unità di misura devono anche essere adattati al mercato di destinazione. Capita spesso di vedere documenti tecnici tradotti in inglese in cui il separatore dei decimali e delle migliaia è usato secondo lo standard italiano. In inglese i numeri decimali sono separati dal punto e le migliaia della virgola:

• inglese: 15.10 - italiano: 15,10
• inglese: 10,000 - italiano: 10.000

La confusione può aumentare se dal contesto non è chiaro l’ordine di grandezza e la cifra ha tre decimali:

390,142

Significa trecentonovantamila… o 390 virgola…?

Le unità di misura devono essere convertite al sistema in uso nel mercato al quale il manuale è destinato. Ci sono sistemi, infatti, che non usano la suddivisione decimale, come il sistema imperiale britannico di unità di misura, usato nel Regno Unito, in Canada, Australia, ma anche nelle Filippine, per citare solo alcuni paesi, e il sistema consuetudinario statunitense di unità.

Prendiamo come esempio le misure di lunghezza: mentre noi utilizziamo il sistema metrico decimale, con i centimetri e i relativi multipli o sottomultipli, il sistema britannico e quello statunitense utilizzano il sistema imperiale, con pollici e piedi. Un pollice (simbolo: in) corrisponde a 2,54 cm, mentre un piede (ft) a 30,50 cm. In questo caso i valori sono uguali in entrambi i sistemi. Se, però, ci soffermiamo sulle misure di capacità, vediamo che un gallone (Imp gal) corrisponde a 4,54 l nel sistema britannico e a 3,78 l in quello statunitense.

È importante essere consapevoli di queste differenze sia per permettere all’utente di capire i dati riportati sia perché il mancato adattamento di un’unità di misura può portare a errori anche gravi.

8. Non scrivere le istruzioni nell’ordine logico in cui vanno eseguite

Per favorire la comprensione delle istruzioni, e quindi per consentire all’utente di essere subito operativo, le informazioni devono essere presentate in modo chiaro e ordinato.

Gli accorgimenti fondamentali sono due:

• ogni frase deve esprimere un solo concetto;
• le istruzioni devono essere riportate nell’ordine logico e temporale con cui devono essere svolte.

Questa frase contiene diverse informazioni e la sequenza delle azioni non rispecchia l’ordine con cui devono essere eseguite. Possiamo renderla più chiara:

Oltre ad aver riscritto la frase, abbiamo esposto le informazioni in modo ordinato usando gli elenchi: uno puntato e uno numerato. L’elenco puntato introduce una lista di elementi, mentre quello numerato indica l’ordine con cui svolgere le azioni.

9. Non migliorare la scrittura con i linguaggi controllati

I linguaggi controllati sono lingue naturali che usano un numero ridotto di regole sintattico-stilistiche e di vocaboli. Sono stati sviluppati per semplificare e standardizzare la redazione di documenti tecnici, per migliorare la leggibilità e la comprensibilità dei testi, e ridurre le ambiguità.

I più conosciuti sono:

• la specifica ASD-STE100, o Simplified Technical English, usato nell’industria aerospaziale;
• l’Italiano Tecnico Semplificato (ITS), sviluppato da Com\&Tec, l’Associazione Italiana per la Comunicazione Tecnica;
• l’Español Técnico Simplificado (ETS) per lo spagnolo;
• il Français Rationalisé per il francese.

Come sono strutturati i linguaggi controllati?

Sia l’Italiano Tecnico Semplificato sia il Simplified Technical English sono strutturati in due sezioni:

• le istruzioni linguistiche;
• il dizionario.

Le istruzioni linguistiche descrivono le regole grammaticali, sintattiche e stilistiche della lingua, mentre il vocabolario raccoglie un numero ridotto di voci che si possono utilizzare per scrivere un testo.

Quali sono le regole dei linguaggi controllati?

Ogni linguaggio controllato ha le proprie regole, ma possono essere individuati dei principi comuni:

• una frase deve contenere un numero limitato di parole, 25-30 al massimo;
• ogni frase deve esprimere un solo concetto;
• scrivi sempre la stessa frase per esprimere lo stesso concetto;
• usa la forma attiva e non la forma passiva;
• non usare modi verbali di difficile interpretazione come il congiuntivo o il condizionale, ma preferisci l’indicativo;
• non omettere il soggetto, gli articoli o gli aggettivi dimostrativi;
• non usare i pronomi, ma ripeti il nome;
• non usare sinonimi, ma ripeti la parola o il termine;
• non usare espressioni idiomatiche.

Se le prescrizioni risultano complesse o rigide, se non ci sono le risorse per adottare un linguaggio controllato nella sua interezza o se non è possibile rivolgersi ad esperti esterni, non è necessario applicarle tutte.

Si può prendere spunto dai principi e creare delle regole aziendali di scrittura e preparare delle liste con la terminologia ufficiale o con le parole da preferire o da evitare.

I linguaggi controllati non sono stati sviluppati solo per migliorare la comunicazione scritta in ambito tecnico, ma anche per aumentare la traducibilità dei testi. Grazie alla coerenza alla base delle scelte linguistiche e alla semplificazione delle strutture, permettono di ridurre i tempi e costi di traduzione. Inoltre, sono particolarmente adatti anche per redigere testi che devono essere tradotti con sistemi di traduzione automatica.

Se vuoi approfondire l’argomento, sul nostro blog trovi il post “Il linguaggio controllato” con un’intervista a Daniela Zambrini, associate member di STEMG dal 2014, il gruppo di lavoro incaricato della manutenzione della specifica ASD-STE100.

10. Non strutturare le informazioni in modo logico e ordinato

Un manuale non è un libro. L’utente medio di solito non lo legge dalla prima all’ultima pagina.

Quante volte acquistiamo un prodotto e cerchiamo di farlo funzionare senza leggere le istruzioni? A un certo punto, ci rendiamo conto che non ne siamo capaci e iniziamo a sfogliare il manuale in cerca dell’informazione che ci serve. Oppure riusciamo a montarlo, ma non sappiamo che cos’è quell’ultimo componente che non sappiamo dove mettere e in tutto il documento non troviamo nemmeno come si chiama.

A meno che le istruzioni non siano di due pagine, è utile inserire:

• un sommario;
• una lista delle abbreviazioni;
• un indice delle figure e delle tabelle;
• una lista delle parole chiave in ordine alfabetico;
• gli esplosi con i componenti e la legenda;
• un glossario che raccoglie i termini tecnici e li spiega.

Tutti questi elementi permettono all’utente di trovare facilmente quello che sta cercando.

Chi lavora nel campo della manualistica e del technical writing usa (o dovrebbe usare) appositi software per la creazione e la gestione dei documenti tecnici e dei manuali. Si tratta di strumenti che permettono di superare i limiti di Word o di InDesign e che facilitano notevolmente la gestione dei contenuti e degli aggiornamenti.

Vengono raggruppati sotto l’acronimo CCMS, che sta per Component Content Management System e fa riferimento alla loro funzione principale: la possibilità di strutturare il contenuto in modo granulare, per componenti, anziché a livello di documento.

Per intenderci, se i manuali d’uso e manutenzione di macchine o prodotti diversi condividono le stesse avvertenze di sicurezza o le stesse note relative alla pulizia, i software CCMS consentono di creare tale contenuto comune una sola volta per poi riutilizzarlo tutte le volte che è necessario.

Questi sistemi usano solitamente formati standard per la creazione di informazioni strutturate. I due standard più noti sono:

• DITA (Darwin Information Typing Architecture) e
• DocBook

ma ne esistono anche altri settoriali, come SCORM per la creazione di contenuti formativi o S1000D per il settore della difesa e aerospaziale.

11. Usare illustrazioni di bassa qualità o poco chiare

In un manuale non è importante solo il contenuto, ma anche l’aspetto grafico e le informazioni visive. Ricorda che, molto probabilmente, il manuale non verrà letto su una scrivania, ma in postazioni di lavoro poco agevoli, con scarsa illuminazione o in spazi ristretti.

Titoli, grassetti, paragrafi sufficientemente distanziati e note ai margini delle pagine facilitano la lettura, così come gli elementi visivi che supportano il testo. Immagini, disegni, esplosi, tabelle e pittogrammi attirano l’attenzione, facilitano la comprensione, permettono di scrivere meno e, quindi, di risparmiare fra l’altro sul costo della traduzione.

Prendiamo questa immagine tratta dal manuale istruzioni di un seggiolino per l’auto:

Fonte: https://www.chicco.it/content/dam/chicco/it/pdf/in-viaggio/seggiolini-auto/8058664079445/youniverse-manuale-istruzioni.pdf

L’immagine è chiara: basta un solo colpo d’occhio per capire che la distanza tra la parte inferiore del poggiatesta e la spalla del bambino deve essere di due centimetri.

Figure e tabelle devono essere numerate e devono essere accompagnate da una didascalia. Inoltre, devono essere sempre aggiornate: se una revisione al testo coinvolge anche l’immagine, questa deve essere modificata di conseguenza.

Nei manuali multilingui, se le immagini contengono del testo, anche questo deve essere tradotto. Per approfondire l’argomento puoi leggere il nostro post “Come tradurre il testo contenuto nelle immagini”.

Come verificare se un manuale è comprensibile?

Gli autori dei manuali sono spesso esperti del settore e potrebbero dare per scontati aspetti che non lo sono affatto per l’utente finale. Un modo per verificare se il contenuto è chiaro, è far leggere il documento a chi non conosce il prodotto e, soprattutto, far eseguire le azioni richieste.

Nonostante questo accorgimento, non è sempre possibile prevedere tutte le criticità. Una volta immesso il prodotto sul mercato, possono giungere segnalazioni e reclami da parte dei clienti. Queste osservazioni sono molto utili e dovrebbero essere sfruttate per migliorare il manuale.

12. Non pianificare la traduzione del manuale fin dalla prima stesura

La “direttiva macchine” stabilisce che “ogni macchina deve essere accompagnata da istruzioni per l’uso nella o nelle lingue comunitarie ufficiali dello Stato membro in cui la macchina è immessa sul mercato e/o messa in servizio.”

Rendere disponibile la documentazione tecnica nelle lingue dei mercati ai quali ti rivolgi non è solo un obbligo di legge, ma ti permette di raggiungere con efficacia i tuoi clienti e, come abbiamo detto all’inizio del post, di ridurre i costi legati all’assistenza.

Molte aziende commettono l’errore di risparmiare sui costi legati alla traduzione: spesso si pensa che sia sufficiente tradurre il manuale in inglese, oppure lo si fa tradurre a personale interno che, per quanto possa essere esperto in un settore, non ha le competenze traduttologiche necessarie.

Quando devi tradurre un manuale:

• leggi la nostra guida per scegliere il fornitore di servizi linguistici più adatto al caso tuo;
• scrivi i contenuti originali considerando che andranno tradotti;
• metti una persona a disposizione del fornitore di traduzione per risolvere eventuali dubbi.

6 concetti per concludere

1. Semplicità, chiarezza e coerenza sono le parole chiave per scrivere un manuale.
2. Il desiderio dell’utente è di usare il prodotto nel minor tempo possibile: inserisci immagini e disegni per facilitare la comprensione ed elementi come il sommario, l’indice delle abbreviazioni e l’elenco delle parole chiave per facilitare la consultazione.
3. Ricorda che l’utente non ha la stessa formazione di chi redige il manuale: non dare niente per scontato.
4. Mettiti nei panni dell’utente e cerca di anticipare le sue domande.
5. Cura le traduzioni come l’originale.
6. Un manuale scritto bene ti permette di ridurre i costi legati alle richieste di assistenza e ai reclami.

Letture consigliate

• Norma IEC 82079-1:2012 “Preparation of instructions for use -- Structuring, content and presentation General principles and detailed requirements” (Preparazione di istruzioni per l’uso – Struttura, contenuto e presentazione), disponibile a pagamento sul sito dell’UNI, l’Ente italiano di normazione.
• Specifica ASD-STE100 (Simplified Technical English).
• Italiano Tecnico Semplificato di Ilaria Gobbi.
• Guía de español técnico simplificado. Un lenguaje controlado para la redacción de manuales técnicos en español di Ilaria Gobbi.