Istruzioni

L’obiettivo di questo capitolo è uno degli usi più importanti della scrittura tecnica: le istruzioni. Come sapete, le istruzioni sono quelle spiegazioni passo per passo su come fare qualcosa: come costruire, far funzionare, riparare o mantenere le cose.

Assicuratevi di controllare gli esempi.

Scrivere istruzioni

Uno degli usi più comuni e più importanti della scrittura tecnica sono le istruzioni, quelle spiegazioni passo per passo su come fare le cose: assemblare qualcosa, far funzionare qualcosa, riparare qualcosa o fare manutenzione ordinaria su qualcosa. Ma per qualcosa che sembra così facile e intuitivo, le istruzioni sono alcuni dei documenti peggio scritti che si possano trovare. Come me, probabilmente avete avuto molte esperienze esasperanti con istruzioni scritte male. Quello che segue in questo capitolo potrebbe non essere una guida infallibile e a prova di errore per scrivere istruzioni, ma vi mostrerà quelle che i professionisti considerano le tecniche migliori.

In definitiva, una buona scrittura di istruzioni richiede:

• Scrittura chiara e semplice
• Comprensione approfondita della procedura in tutti i suoi dettagli tecnici
• La tua capacità di metterti nei panni del lettore, la persona che cerca di usare le tue istruzioni
• La tua capacità di visualizzare la procedura in grande dettaglio e di catturare questa consapevolezza sulla carta
• Infine, la tua volontà di fare quel passo in più e testare le tue istruzioni sul tipo di persona per cui le hai scritte.

Ora probabilmente avete studiato le intestazioni, le liste e gli avvisi speciali – scrivere una serie di istruzioni con questi strumenti probabilmente sembra ovvio. Basta suddividere la discussione in elenchi verticali numerati e inserire alcuni avvisi speciali nei punti più ovvi e il gioco è fatto! Beh, non proprio, ma è un ottimo inizio. Questo capitolo esplora alcune delle caratteristiche delle istruzioni che possono renderle più complesse. Potete a vostra volta usare queste considerazioni per pianificare le vostre istruzioni.

Alcuni Preliminari

All’inizio di un progetto per scrivere istruzioni, è importante determinare la struttura o le caratteristiche della particolare procedura di cui state per scrivere.

Pubblico e situazione. All’inizio del processo, definite il pubblico e la situazione delle vostre istruzioni. Ricordate che definire un pubblico significa definire il suo livello di familiarità con l’argomento e altri dettagli simili. Vedi la discussione sul pubblico e i passi da usare nel definire il pubblico.

Più importante, se sei in un corso di scrittura, dovrai scrivere una descrizione del tuo pubblico e allegarla alle tue istruzioni. Questo permetterà al vostro istruttore di valutare le vostre istruzioni in termini di correttezza per il pubblico a cui sono destinate. E ricordate anche che in un corso di scrittura tecnica è preferibile scrivere per un pubblico non specialistico – molto più di una sfida per voi come scrittore.

Numero di compiti. Quanti compiti ci sono nella procedura di cui state scrivendo? Usiamo il termine procedura per riferirci all’insieme delle attività che le vostre istruzioni intendono trattare. Un compito è un gruppo semi-indipendente di azioni all’interno della procedura: per esempio, impostare l’orologio su un forno a microonde è un compito nella grande procedura complessiva del funzionamento di un forno a microonde.

Una procedura semplice come cambiare l’olio in un’auto contiene solo un compito; non ci sono raggruppamenti semi-indipendenti di attività. Una procedura più complessa come l’uso di un forno a microonde contiene molti di questi compiti semi-indipendenti: impostare l’orologio; impostare il livello di potenza; usare il timer; pulire e mantenere il microonde, tra gli altri. (Le istruzioni sull’uso di una macchina fotografica sono organizzate per compiti.)

Alcune istruzioni hanno solo un singolo compito, ma hanno molti passi all’interno di quel singolo compito. Per esempio, immaginate una serie di istruzioni per assemblare un’altalena per bambini. Nella mia esperienza personale, c’erano più di 130 passi! Questo può essere un po’ scoraggiante. Un buon approccio è quello di raggruppare passi simili e correlati in fasi, e iniziare a rinumerare i passi ad ogni nuova fase. Una fase è quindi un gruppo di passi simili all’interno di una procedura a compito singolo. Nell’esempio dell’altalena, impostare il telaio sarebbe una fase; ancorare la cosa nel terreno sarebbe un’altra; assemblare l’altalena sarebbe ancora un’altra.

Il miglior approccio al discorso delle fasi. Un’altra considerazione, che forse non potete determinare in anticipo, è come focalizzare le vostre istruzioni. Per la maggior parte delle istruzioni, potete concentrarvi sui compiti, o potete concentrarvi sugli strumenti (o sulle caratteristiche degli strumenti).

In un approccio ai compiti (noto anche come orientamento ai compiti) alle istruzioni sull’uso di un servizio di risposta al telefono, avreste queste sezioni:

• registrare il tuo saluto
• riprodurre i tuoi messaggi
• salvare i tuoi messaggi
• inoltrare i tuoi messaggi
• cancellare i tuoi messaggi, e così via

Questi sono compiti – le cose tipiche che vorremmo fare con la macchina. Per ulteriori discussioni, vedere il capitolo sull’analisi dei compiti.

D’altra parte, in un approccio di strumenti alle istruzioni sull’uso di una fotocopiatrice, ci sarebbero queste improbabili sezioni:

• pulsante copia
• pulsante annulla
• pulsante ingrandisci/riduci
• pulsante incolla/stacca
• pulsante tagliacopia, e così via

Se tu progettassi un set di istruzioni su questo piano, scriveresti i passi per usare ogni pulsante o caratteristica della fotocopiatrice. Le istruzioni che usano questo approccio di strumenti sono difficili da far funzionare. A volte, il nome del pulsante non corrisponde esattamente al compito a cui è associato; a volte bisogna usare più di un pulsante per realizzare il compito. Tuttavia, ci possono essere momenti in cui l’approccio strumenti/funzioni può essere preferibile.

Gruppi di compiti. Elencare i compiti potrebbe non essere tutto ciò che è necessario fare. Ci possono essere così tanti compiti che è necessario raggrupparli in modo che i lettori possano trovare i singoli compiti più facilmente. Per esempio, i seguenti sono raggruppamenti di compiti comuni nelle istruzioni:

1. compiti di disimballaggio e configurazione
2. compiti di installazione e personalizzazione
3. compiti operativi di base
4. compiti di manutenzione ordinaria
5. compiti di risoluzione dei problemi; e così via

Sezioni comuni nelle istruzioni

Quella che segue è una rassegna delle sezioni che troverete comunemente nelle istruzioni. Non date per scontato che ognuna di esse debba essere presente nelle istruzioni che scrivete, né che debbano essere nell’ordine presentato qui, né che queste siano le uniche sezioni possibili in un insieme di istruzioni.

Mentre leggete quanto segue sulle sezioni comuni nelle istruzioni, controllate le istruzioni di esempio.

Vista schematica delle istruzioni. Ricorda che questo è un modello tipico o comune per il contenuto e l’organizzazione – molti altri sono possibili.

Introduzione. Pianificate attentamente l’introduzione alle vostre istruzioni. Assicuratevi che faccia una qualsiasi delle seguenti cose (ma non necessariamente in quest’ordine) che si applicano alle vostre particolari istruzioni:

• Indicare i compiti specifici o la procedura da spiegare così come l’ambito di copertura (cosa non sarà coperto).
• Indicare di cosa ha bisogno il pubblico in termini di conoscenza e di background per capire le istruzioni.
• Dare un’idea generale della procedura e di ciò che essa realizza.
• Indicare le condizioni in cui queste istruzioni dovrebbero (o non dovrebbero) essere usate.
• Dare una panoramica del contenuto delle istruzioni.

Vedere la sezione sulle introduzioni per ulteriori discussioni.

Avvertenze generali, attenzione, avvisi di pericolo. Le istruzioni devono spesso avvertire i lettori della possibilità di rovinare la loro attrezzatura, sbagliare la procedura e farsi male. Inoltre, le istruzioni devono spesso sottolineare punti chiave o eccezioni. Per queste situazioni si usano avvisi speciali: avvisi di nota, avvertimento, attenzione e pericolo. Notate come questi avvisi speciali sono usati nelle istruzioni di esempio elencate sopra.

Sfondo tecnico o teoria. All’inizio di alcuni tipi di istruzioni (dopo l’introduzione, naturalmente), potrebbe essere necessaria una discussione sul background relativo alla procedura. Per alcune istruzioni, questo background è fondamentale, altrimenti i passi della procedura non hanno senso. Per esempio, potreste aver avuto qualche esperienza con quelle applet software in cui si definiscono i propri colori muovendo le barre di scorrimento rosse, verdi e blu. Per capire davvero quello che state facendo, dovete avere un po’ di background sul colore. Allo stesso modo, si può immaginare che, per certe istruzioni che usano le macchine fotografiche, sia necessaria anche un po’ di teoria.

Attrezzature e forniture. Notate che la maggior parte delle istruzioni include una lista delle cose che dovete raccogliere prima di iniziare la procedura. Questo include l’attrezzatura, gli strumenti che si usano nella procedura (come ciotole per mescolare, cucchiai, teglie per il pane, martelli, trapani e seghe) e le forniture, le cose che si consumano nella procedura (come legno, vernice, olio, farina e chiodi). Nelle istruzioni, queste cose sono tipicamente elencate in una semplice lista verticale o in una lista a due colonne. Usate l’elenco a due colonne se avete bisogno di aggiungere alcune specifiche ad alcuni o a tutti gli elementi – per esempio, nomi di marche, dimensioni, quantità, tipi, numeri di modello, e così via.

Discussione dei passi. Quando si arriva alla scrittura effettiva dei passi, ci sono diverse cose da tenere a mente: (1) la struttura e il formato di quei passi, (2) le informazioni supplementari che potrebbero essere necessarie, e (3) il punto di vista e lo stile generale di scrittura.

Struttura e formato. Normalmente, immaginiamo che un insieme di istruzioni sia formattato come liste verticali numerate. E la maggior parte lo sono in effetti. Normalmente, si formattano le istruzioni passo dopo passo in questo modo. Ci sono alcune variazioni, tuttavia, così come alcune altre considerazioni:

• I passi di ordine fisso sono passi che devono essere eseguiti nell’ordine presentato. Per esempio, se state cambiando l’olio in un’auto, scaricare l’olio è un passo che deve venire prima di mettere l’olio nuovo. Queste sono liste numerate (di solito, liste numerate verticalmente).
• I passi di ordine variabile sono passi che possono essere eseguiti praticamente in qualsiasi ordine. Buoni esempi sono quelle guide per la risoluzione dei problemi che ti dicono di controllare questo, controllare quello, quando stai cercando di riparare qualcosa. Puoi fare questo tipo di passi praticamente in qualsiasi ordine. Con questo tipo, l’elenco puntato è il formato appropriato.
• I passi alternativi sono quelli in cui vengono presentati due o più modi per realizzare la stessa cosa. I passi alternativi si usano anche quando possono esistere varie condizioni. Usare elenchi puntati con questo tipo, con OR inseriti tra le alternative, o il lead-in che indica che le alternative stanno per essere presentate.
• Passi annidati. In alcuni casi, i singoli passi di una procedura possono essere piuttosto complessi di per sé e devono essere suddivisi in sottopassi. In questo caso, si indentano ulteriormente e si mettono in sequenza i sottopassi come a, b, c, e così via.
• Istruzioni “senza passi”. E infine ci sono istruzioni che davvero non possono usare l’elenco verticale numerato e che fanno poco, se non nulla, di diretto stile istruttivo per il lettore. Alcune situazioni devono essere così generalizzate o così variabili che i passi non possono essere indicati.

Si veda il capitolo sulle liste per lo stile e il formato di queste possibilità. Spesso, non è sufficiente dire ai lettori di fare questo o quello. Hanno bisogno di informazioni esplicative aggiuntive come il modo in cui la cosa dovrebbe apparire prima e dopo il passo; perché dovrebbero preoccuparsi di fare questo passo; qual è il principio meccanico dietro a quello che stanno facendo; una spiegazione ancora più micro-livello del passo – la discussione delle azioni specifiche che compongono il passo.

Il problema con la discussione supplementare, tuttavia, è che può nascondere il passo effettivo. Voi volete che il passo vero e proprio – le azioni specifiche che il lettore deve compiere – risalti. Non volete che sia tutto sepolto in un mucchio di parole. Ci sono almeno due tecniche per evitare questo problema: si può dividere l’istruzione dal supplemento in paragrafi separati; oppure si può mettere in grassetto l’istruzione.

Mettere in grassetto i passi effettivi dell’utente nelle istruzioni. Il testo in grassetto aiuta a distinguere l’azione reale dalle informazioni supplementari.

Stile di scrittura. Il modo in cui scrivete effettivamente le istruzioni, frase per frase, può sembrare in contraddizione con ciò che vi hanno insegnato i corsi di scrittura precedenti. Tuttavia, notate come sono scritte le istruzioni del “mondo reale” – usano molto il tipo di scrittura imperativa (comando, o indirizzo diretto); usano molto il “tu”. Questo è del tutto appropriato. Volete andare in faccia al vostro lettore, ottenere la sua piena attenzione. Per questo motivo, le frasi in stile istruzione suonano come queste: “Ora, premi il pulsante Pausa sul pannello frontale per fermare temporaneamente il display” e “Dovresti stare attento a non…”

Un problema particolare riguarda l’uso della voce passiva nelle istruzioni. Per qualche strana ragione, alcune istruzioni suonano così: “Il pulsante Pause dovrebbe essere premuto per fermare temporaneamente il display”. Non solo siamo preoccupati per la salute mentale del pulsante Pause, ma ci chiediamo anche chi dovrebbe premerlo (stai parlando con me?). O considerate questo esempio: “Il pulsante Timer è quindi impostato su 3:00”. Di nuovo, come persona che segue queste istruzioni, potreste non accorgervene; potreste pensare che sia semplicemente un riferimento a qualche stato esistente, o potreste chiedervi: “Stanno parlando con me?” Quasi altrettanto brutto è usare la terza persona: “L’utente dovrebbe poi premere il pulsante Pausa”. Ancora una volta, è il vecchio double-take: vi guardate intorno nella stanza e vi chiedete: “Chi io?”. (Per maggiori dettagli, vedi il problema della voce passiva.)

Un altro dei problemi tipici dello stile di scrittura nelle istruzioni è che la gente sembra voler tralasciare gli articoli: “Premere il pulsante Pause sul pannello frontale per fermare temporaneamente la visualizzazione delle informazioni” o “Terrestre, per favore fornisci l’indirizzo della pizzeria più vicina”. Perché lo facciamo? Vogliamo tutti segretamente essere dei robot? Comunque, assicuratevi di includere tutti gli articoli (a, an, the) e altre parole simili che useremmo normalmente nelle istruzioni.

La grafica nelle istruzioni

Probabilmente più che in qualsiasi altra forma di scrittura (eccetto forse i fumetti), la grafica è cruciale per le istruzioni. A volte, le parole semplicemente non possono spiegare il passo. Le illustrazioni sono spesso critiche per la capacità dei lettori di visualizzare ciò che devono fare.

In un corso di scrittura tecnica, le istruzioni possono richiedere di includere illustrazioni o altri tipi di grafica – qualsiasi cosa venga normalmente usata nelle istruzioni. Il problema, naturalmente, può essere che non hai accesso a grafici che sarebbero adatti alle tue particolari istruzioni, e che non ti senti molto sicuro delle tue capacità artistiche. Ci sono modi per superare questi problemi! Date un’occhiata ai suggerimenti in grafica. In quel capitolo, vedrai non solo suggerimenti per creare grafici, ma anche requisiti sul loro formato.

Formato nelle istruzioni

Titoli. Nelle tue istruzioni, fai buon uso dei titoli. Normalmente, vorresti delle intestazioni per ogni sezione di sfondo che potresti avere, la sezione sull’attrezzatura e le forniture, un’intestazione generale per la sezione delle istruzioni vere e proprie, e delle sottointestazioni per i singoli compiti o fasi all’interno di quella sezione. Dai un’occhiata agli esempi all’inizio di questo capitolo. Vedere le intestazioni per i requisiti comuni.

Liste. Allo stesso modo, le istruzioni fanno tipicamente un uso pesante di liste, in particolare liste verticali numerate per le effettive spiegazioni passo dopo passo. Semplici elenchi verticali o elenchi a due colonne sono solitamente buoni per la sezione delle attrezzature e delle forniture. Gli elenchi di frasi sono buoni quando si dà una panoramica delle cose da fare. Vedi le liste per i requisiti comuni.

Avvisi speciali. Nelle istruzioni, dovete avvertire i lettori delle possibilità in cui possono danneggiare la loro attrezzatura, sprecare le forniture, far fallire l’intera procedura, ferire se stessi o altri – anche gravemente o mortalmente. Le aziende sono state citate in giudizio per la mancanza di questi avvisi speciali, per avvisi speciali scritti male, o per avvisi speciali che erano fuori posto. Vedi avvisi speciali per una discussione completa sull’uso appropriato di questi avvisi speciali così come il loro formato e posizionamento all’interno delle istruzioni.

Indentazione degli avvisi nelle istruzioni. Nel primo esempio, notate come l’avviso è indentato rispetto al testo del passo precedente. Nel secondo esempio, notate che il severo avviso è posto all’inizio prima di qualsiasi passo.

Numero, abbreviazioni e simboli. Le istruzioni usano anche molti numeri, abbreviazioni e simboli. Per le linee guida su queste aree.

Lista di controllo per la revisione delle istruzioni

Quando rileggi e rivedi le tue istruzioni, fai attenzione a problemi come i seguenti:

• Assicurati di fornire vere istruzioni, spiegazioni su come costruire, far funzionare o riparare qualcosa.
• Scrivi una buona introduzione, indicando l’esatta procedura da spiegare, i requisiti del pubblico e una panoramica dei contenuti.
• Assicuratevi di usare i vari tipi di elenchi dove è opportuno. In particolare, usate elenchi verticali numerati per i passi sequenziali.
• Utilizzate i titoli per delimitare tutte le sezioni principali e i sottotitoli per le sottosezioni. (Ricorda che non è necessaria l’intestazione “Introduzione” tra il titolo e il primo paragrafo. Ricorda di non usare intestazioni di primo livello in questo compito; inizia con il secondo livello.)
• Usa gli avvisi speciali come appropriato.
• Assicurati di usare lo stile e il formato per tutte le intestazioni, liste, avvisi speciali e grafici come presentato in questi capitoli. Se questo è un problema, mettiti in contatto con il tuo istruttore.
• Utilizza i grafici per illustrare qualsiasi azione o oggetto chiave.
• Fornisci ulteriori spiegazioni supplementari dei passi, se necessario.
• Ricordati di creare una sezione che elenchi attrezzature e forniture, se necessario.

Apprezzerei i tuoi pensieri, reazioni, critiche riguardanti questo capitolo: la tua risposta-David McMurrey.