Guida al Technical Writing

Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel. / Fax: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
Guida al Technical Writing
Report sul libro di Krista Van Laan, The Insider’s Guide to Technical Writing, XML
Press, Laguna Hill, California, 2012.
Un’interessante guida in inglese, scritta dall’esperta di technical writing Krista Van
Laan. A di là della sua focalizzazione sul contesto statunitense e sulla scrittura di
manuali per software, è un libro ricchissimo di spunti sulla funzione strategica della
documentazione tecnica, sulla centralità dei destinatari, sui concetti di
frammentazione e gestione strutturata dei contenuti, single sourcing, tagging,
riutilizzo dei contenuti e multicanalità, nonché su come produrre buona
documentazione: corretta e completa, fruibile, usabile e ricercabile, chiara e
coerente.
Professione “technical writer”
Krista Van Laan inquadra nel contesto statunitense la professione di technical writer, facendo riferimento in
particolare alla Society for Technical Communication (http://www.stc.org/) e alla certificazione di Certified
Professional Technical Writer e Certified Professional Technical Communicator che essa rilascia
(http://www.stc.org/education/certification/certification-main).
Che negli USA quella del redattore tecnico / comunicatore tecnico siano professionalità riconosciute è
testimoniato anche dalla pagina web che l’US Department of Labor Bureau of Labor Statistics
(http://www.bls.gov/ooh/media-and-communication/technical-writers.htm) a informazioni su come
diventare techical writer, sulle prospettive di impiego, sulla retribuzione attesa, ecc.
Krista Van Laan sottolinea che, dato il ruolo centrale del technical writer come “traduttore” fra sapere
aziendale e destinatari del prodotto, è utile che i redattori tecnici acquisiscano anche competenze
nell’ambito del project management (vd. Project Management Institute http://www.pmi.org/ e le
certificazioni proposte dall’istituto http://www.pmi.org/Certification.aspx).
Infine, fra i numerosi link utili, segnaliamo in particolare quello a TechWhirl (http://techwhirl.com/),
magazine dedicato ai sistemi di gestione dei contenuti (Content Management Systems – CMS), technical
communication e technical writing.
Funzione strategica della buona documentazione tecnica
In vari punti del suo libro Krista Van Laan sottolinea il ruolo strategico della documentazione tecnica
all’interno dell’azienda. In quanto parte costitutiva del prodotto, la buona documentazione contribuisce a:
• Ridurre tempi e costi di assistenza
• Incrementare la soddisfazione del cliente
• Trasformare il cliente in cliente fedele
• Ingenerare un passaparola positivo sul prodotto e sull’azienda.
1

Tel. / Fax: +39 045 6152381
Centralità del destinatario nella redazione della documentazione tecnica
Il technical writer va visto come “traduttore” fra il sapere interno all’azienda (quello di chi progetta e
produce il prodotto) e i destinatari del prodotto, ognuno dei quali si rapporta a esso da una diversa base di
partenza: potenziali clienti, installatori, utilizzatori e manutentori, formatori, ecc.
Il redattore tecnico ha il compito di evitare sovraccarichi informativi, comunicando a ogni tipo di
destinatario informazioni necessarie al corretto utilizzo del prodotto e coerenti con il suo background e
linguaggio.
Krista Van Laan sottolinea che non vi sono solo vari tipi di destinatari, ma che ogni tipo di destinatario può
avere un diverso grado di conoscenza del prodotto, dal neofita all’esperto.
Per scrivere documentazione tecnica efficace, va quindi tenuta in considerazione sia la tipologia che la
competenza del destinatario. Inoltre è necessario porsi alcuni quesiti preliminari:
• Quali sono gli obiettivi dell’utente e i passaggi necessari per raggiungerli? Ovvero:
• Qual è il flusso di lavoro dell’utente?
• Che problemi può incontrare?
• Qual è il contesto di utilizzo della documentazione?
• Qual è la frequenza di consultazione?
Sulle esigenze dei destinatari si basa quindi la scelta dei:
• Tipi di documentazione da redigere
• Canali di pubblicazione.
Obiettivo è fornire a ogni destinatario le informazioni di cui ha bisogno, nei tempi e luoghi opportuni.
Per migliorare nel tempo la documentazione tecnica, Krista Van Laan consiglia di tenere traccia di quesiti e
desiderata degli utenti, facendoli confluire in successive versioni.
Frammentazione e gestione strutturata dei contenuti, single sourcing,
tagging, riutilizzo dei contenuti, multicanalità
Krista Van Laan presenta concetti, metodiche e strumenti che permettono di agevolare la gestione dei
contenuti e la pubblicazione multicanale dei vari tipi di documentazione, tenendo in considerazione la
manutenibilità delle informazioni, la coerenza di contenuti e presentazione, l’esigenza di tradurre e
localizzare i dati, il rispetto delle scadenze e la scarsità di organico spesso lamentata dagli uffici
documentazione tecnica.
Le parole chiave intorno alle quali ruota l’esposizione di Krista Van Laan sono:
• Chunking (frammentazione) dei contenuti in unità logiche elementari
2

Tel. / Fax: +39 045 6152381
• Il primo passo è il chunking, cioè la frammentazione dei contenuti in unità logiche elementari,
ovvero in componenti (chunks o topic) riutilizzabili all’interno dei vari tipi di documentazione,
destinati ai vari canali di pubblicazione. Questa tecnica di redazione, chiamata topic-oriented
writing, richiede che i contenuti siano frammentati in modo tale da poter essere utilizzati sia stand-
alone che in sequenza. La granularità dei frammenti può essere la più varia: termini, espressioni,
paragrafi, warning, immagini, tabelle, capitoli, ecc.
• Gestione strutturata dei contenuti
• Chunking e topic-oriented writing implicano la necessità di gestire i contenuti in modo strutturato.
Krista Van Laan illustra i vantaggi dell’adozione di software di structured authoring basati su XML:
• Il primo vantaggio sta nella possibilità di strutturare determinati tipi di contenuti (per esempio le
procedure) a partire da modelli standardizzati, chiamati schemi o DTD – Document Type
Definition. E’ possibile adottare schemi “universali” (come DITA) o schemi appartenenti a un
determinato settore industriale (per esempio AECMA S1000D per il settore aerospaziale) oppure
schemi proprietari dell’azienda
• Gli altri vantaggi principali derivati dalla frammentazione e strutturazione dei contenuti sono:
• Separazione fra contenuto e presentazione
• Automazione degli output multicanale
• Riutilizzo dei contenuti.
• Single sourcing
• Per ottimizzare l’efficienza del processo di redazione, traduzione e localizzazione, i contenuti non
vanno solo frammentati e strutturati, ma anche gestiti in modo univoco (single sourcing). Per ogni
componente di contenuto va gestito, manutenuto, tradotto / localizzato una sola volta, per poter
poi essere ripreso in modo coerente nei vari tipi di documentazione
• Tagging dei contenuti
• La marcatura (tagging) dei topic è fondamentale per definirne il contesto di riutilizzo. Krista Van
Laan distingue tra due famiglie di tag:
• Task-based
• Pongono al centro l’utente. Sono utili per contrassegnare contenuti che descrivono il flusso
di lavoro dell’utente (workflow), gli obiettivi operativi che si prefigge e i passaggi che deve
compiere per raggiungerli (task)
• Referenze-based
• Pongono al centro il prodotto. Sono utili per contrassegnare contenuti da inserire
all’interno di glossari, release note, reference guide, ecc., cioè nei documenti incentrati
sulle funzioni del prodotto
3

Tel. / Fax: +39 045 6152381
• Riutilizzo dei contenuti
• Ai tag si applicano i set di condizioni di riutilizzo dei topic, che permettono di automatizzare la
ripresa dei contenuti opportuni all’interno dei vari tipi di documentazione, per i vari destinatari e
canali di pubblicazione
• Tipi di documentazione multicanale
• Krista Van Laan offre una panoramica dei tipi di documentazione tecnica che può essere utile
realizzare per i vari destinatari:
• Manuale di installazione su carta e in PDF per installatori (nel caso di macchinari) o utilizzatori
neofiti (nel caso di prodotti consumer)
• Manuale utente su carta e in PDF per utilizzatori di ogni livello
• Tutorial, guida rapida, quick start, getting started su carta, PDF oppure online, meglio se in
formato video o interattivo. Si tratta in genere di documentazione per utilizzatori neofiti, pensata
per essere utilizzata una solo volta o comunque di rado
• Manuale di manutenzione per manutentori (nel caso di macchinari)
• Help online per utilizzatori di ogni livello
• Guida ai messaggi di errore, troubleshooting su carta, PDF oppure online, per utilizzatori di ogni
livello
• Documentazione per il “self-help”
• Knowledge base, forum, blog, social network per utilizzatori di ogni livello
• Wiki, in particolare per la condivisione di sapere all’interno dell’azienda
• Release note, con indicazione di novità, bug fix, bug noti e workaround
• Documentazione interna per gli uffici marketing, commerciale e amministrazione
• Documentazione interna relativa allo sviluppo del prodotto, contenente i must, could, should e
won’t delle nuove versioni del prodotto.
Altri fondamenti della buona documentazione tecnica
Frammentazione e gestione strutturata dei contenuti, single sourcing e tagging aiutano a ottimizzare il
processo di redazione, revisione, traduzione e localizzazione, e ad automatizzare la realizzazione di
documentazione multicanale coerente, mirata per i vari destinatari.
Tuttavia, la bontà della documentazione tecnica dipende anche, e soprattutto, dai suoi contenuti, e in
particolare dalla correttezza e completezza, dalla fruibilità, usabilità e ricercabilità, nonché dalla chiarezza e
coerenza delle informazioni.
Correttezza e completezza
Krista Van Laan evidenzia anzitutto i costi della documentazione tecnica non corretta e incompleta:
• Aumento di tempi e costi di assistenza
• Minore soddisfazione del cliente
4

Tel. / Fax: +39 045 6152381
• Passaparola negativo e danno d’immagine per l’azienda.
Correttezza e completezza della documentazione tecnica sono dunque strategiche per l’azienda.
Krista Van Laan descrive il flusso di lavoro (iterativo) che favorisce la produzione di documentazione tecnica
di qualità:
• Raccolta delle informazioni. Il consiglio è di:
• Salvare la versione originale delle informazioni raccolte, marcandole in modo tale che non
confluiscano nella versione finale della documentazione
• Utilizzare segnaposto e marcatori per contrassegnare contenuti incompleti e note per il redattore
• Pianificazione. Riguarda:
• Tipi di documentazione multicanale da produrre per i vari destinatari
• Scadenze
• Redazione. Riguarda:
• Contenuti nuovi
• Modifica di contenuti esistenti, usando di marcatori per tenere traccia delle modifiche e salvando la
versione precedente
• Revisione. Il consiglio è di:
• Utilizzare marcatori per:
• Gestire il flusso di revisione e approvazione
• Inviare a ogni revisore solo i contenuti di sua pertinenza
• Produrre una bozza del documento, completa di note per il redattore, note per il revisore, note
relative a contenuti incompleti, ecc. La bozza va formattata in modo tale da essere facilmente
riconoscibile. E’ consigliabile impaginare la bozza applicando un template grafico apposito, che
renda la bozza inequivocabilmente distinguibile dalla versione finale della documentazione
• Congelamento del documento pubblicato
• Il documento va “congelato” per salvare la versione pubblicata
• Revisione delle parti comuni
• Le revisioni vanno effettuate sulle parti comuni (unità logiche elementari, chunk, topic, frammenti di
contenuto), in modo tale che le modifiche confluiscano nelle versioni successive dei documenti.
5

Tel. / Fax: +39 045 6152381
Fruibilità, usabilità, ricercabilità
La fruibilità della documentazione tecnica dipende dalla scelta del canale di pubblicazione (carta, web,
mobile, app, ecc.): come sottolineato in apertura, l’obiettivo è fornire a ogni destinatario le informazioni di
cui ha bisogno, nei tempi e luoghi opportuni.
Usabilità e ricercabilità del documento sono importanti indicatori di qualità. Krista Van Laan sottolinea in
particolare i seguenti aspetti:
• Illustrazioni, foto, video e interattività per rendere più immediata la comprensione
• Design e layout professionali
• Sommario su 3 livelli al massimo per garantirne la fruibilità ottimale
• Indice analitico per agevolare il reperimento delle informazioni
• Altri indici:
• Per esempio, nel caso di cataloghi è utile l’indice dei codici articolo, mentre in quello di command
reference, la lista dei comandi in ordine alfabetico. Krista Van Laan non attribuisce particolare utilità
all’indice di figure e tabelle: a suo giudizio, se una figura o una tabella sono particolarmente
importanti, è preferibile dotarle di un titolo da includere nel sommario
• Riferimenti incrociati (per la documentazione su carta) e link interni (per la documentazione in formato
digitale)
• Motore di ricerca interno.
Chiarezza
Numerosi i suggerimenti di Krista Van Laan per redigere documentazione chiara:
• Evitare formulazioni ambigue
• Eliminare parole non necessarie
• Usare preferibilmente parole corte e semplici, più facili da leggere e comprendere. Vanno comunque
scelti vocaboli facenti parte del backgroud del destinatario, per cui la “semplicità” è sempre un
concetto relativo
• Usare preferibilmente frasi brevi (ca. 25 parole) e paragrafi brevi (ca. 6 righe)
• Usare la forma attiva, al presente o imperativo (non condizionale) e la seconda persona, più diretta e
meno ambigua
• Usare la forma affermativa, riservando il negativo a note, caution e warning
• Usare elenchi puntati (per attirare l’attenzione) e numerati (per elencare voci in ordine gerarchico, di
importanza). Ogni elenco dovrebbe comporsi di ca. 3-6 voci
• Enfatizzare contenuti importanti usando grassetti, indentature, pittogrammi, ecc. Ciò vale in particolare
per note (che contengono informazioni supplementari), caution (per segnalare possibili danni a cose) e
warning (per segnalare possibili danni a persone)
• Definire e applicare in modo coerente le regole editoriali (vd. sotto).
Coerenza
La coerenza, che contribuisce all’usabilità e alla chiarezza della documentazione tecnica, va applicata a vari
ambiti. Ecco quelli sottolineati in particolare da Krista Van Laan:
6

Tel. / Fax: +39 045 6152381
• Struttura del documento. Ogni documento su carta o in PDF dovrebbe essere strutturato come un
classico libro, prevedendo le seguenti parti:
• Fronte. Comprende:
• Copertina
• Copyright
• Sommario
• Introduzione
• Presentazione di convenzioni tipografiche, pittogrammi, note / caution / warning
• Corpo del documento
• Retro. Comprende:
• Appendice
• Glossario
• Indici
• Regole editoriali. Il consiglio è di definire e adottare a livello aziendale:
• Glossario con abbreviazioni, acronimi, termini accettati
• Regole per:
• Visualizzazione di elenchi puntati e numerati e dei relativi sotto-elenchi
• Uso delle lettere maiuscole
• Formato dei numeri
• Grafia di marchi e nomi di prodotti, modelli, famiglie, ecc.
• Design e layout. Il consiglio è di:
• Preparare un template (modello / foglio di stile) per ogni tipo di documento e per ogni tipo di pagina
• Usare gli spazi bianchi per aumentare la leggibilità del documento. Spazi bianchi, per esempio, prima
dei titoli e dopo i paragrafi (es. 6 punti dopo ogni paragrafo). Per il corpo del testo, impostare la
dimensione del carattere a 10 / 12 punti e un’interlinea ca. 3 volte superiore
• Impostare a ca. 55 / 75 caratteri la lunghezza delle righe
Autore: Petra Dal Santo (dalsanto@keanet.it)
Sito: http://www.keanet.it/
Blog: http://blog.keanet.it/
7

Guida al Technical Writing

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie Guida al Technical Writing

Ähnlich wie Guida al Technical Writing (20)

Mehr von KEA s.r.l.

Mehr von KEA s.r.l. (20)

Guida al Technical Writing