Guida al Technical Writing

  • 270 views
Uploaded on

Report sul libro di Krista Van Laan, The Insider’s Guide to Technical Writing, XML Press, Laguna Hill, California, 2012. …

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.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
270
On Slideshare
0
From Embeds
0
Number of Embeds
2

Actions

Shares
Downloads
16
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. 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
  • 2. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR) Tel. / Fax: +39 045 6152381 Web: www.keanet.it | E-mail: info@keanet.it 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
  • 3. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR) Tel. / Fax: +39 045 6152381 Web: www.keanet.it | E-mail: info@keanet.it • 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
  • 4. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR) Tel. / Fax: +39 045 6152381 Web: www.keanet.it | E-mail: info@keanet.it • 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
  • 5. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR) Tel. / Fax: +39 045 6152381 Web: www.keanet.it | E-mail: info@keanet.it • 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
  • 6. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR) Tel. / Fax: +39 045 6152381 Web: www.keanet.it | E-mail: info@keanet.it 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
  • 7. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR) Tel. / Fax: +39 045 6152381 Web: www.keanet.it | E-mail: info@keanet.it • 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