Nella realtà industriale spesso sono dei tecnici, generalmente degli ingegneri, a scrivere i manuali delle macchine o di un prodotto software.
MA SIAMO COSI’ CONFIDENTI CHE SIA LA SCELTA PIU’ OPPORTUNA ?
Il progettista è in genere la persona meno adatta a spiegare ad altri il funzionamento della sua opera; in altre parole, la sua competenza tecnica specifica non lo rende automaticamente un bravo scrittore-istruttore.
Per quanto controintuitiva possa sembrare tale affermazione, quanto più un tecnico risulta essere un vero specialista, tanto più avrà difficoltà ad adottare quel distacco essenziale per far emergere una visione d'insieme dell'argomento.
Uno specialista è tale quando le nozioni acquisite vengono metabolizzate, interiorizzate e automatizzate. Compiere il percorso inverso, ri-esplicitare la propria conoscenza e saperla comunicare ad utenti meno esperti non è affatto semplice.
Sul piano psicologico, mettersi nei panni di un neofita, comprenderne e anticiparne le difficoltà e facilitare il suo percorso di apprendimento, è un processo estremamente arduo per un esperto.
Il super-esperto, nella migliore delle ipotesi, tende a dare per scontate delle informazioni che invece non risultano affatto banali per il lettore finale del manuale.
Per tale motivo, il buon manuale nasce dall’interazione tra un tecnico e un TW. Il TW affianca il tecnico, pone domande, estrae le conoscenze dalla “pancia” del progettista e le organizza secondo schemi differenziati, in base alla natura del documento che sta scrivendo a al lettore a cui si rivolge, attraverso una prassi in cui si mescolano metodi ben definti e procedimenti “ad hoc”.
Spesso il TW coadiuva il tecnico anche segnalando difetti e potenziali migliorie della macchina o dell'applicazione software che sta usando allo scopo di documentarne il funzionamento.
In quest'ottica, specie nelle aziende più lungimiranti, il TW diviene "consulente" del gruppo di sviluppo tecnico, grazie alla sua capacità di porsi dal punto di vista dell'utilizzatore della macchina/del software.
Ovviamente, se il TW ha competenze tecniche adeguate, il processo d'interazione con il progettista potrà risultare più efficace e spedito.
La mia esperienza in tal senso è un pò atipica, perchè sono un tecnico che ha sempre coltivato la passione per la scrittura ed ho avuto l'opportunità di stare da entrambe le parti della barricata; forse proprio per questo credo di poter dire che saper scrivere un buon manuale è un processo più complesso di quanto non si pensi, in cui "il saper scrivere" occupa un posto sicuramente fondamentale, rispetto alla "conoscenza tecnica dell'argomento".
In altre parole, le nozioni tecniche necessarie si apprendono più facilmente di quanto non si possa imparare a comunicarle efficacemente... e considerato che sono un ingegnere, a questo punto la mia onestà intellettuale mi sembra accertata oltre ogni ragionevole dubbio!
Leggi questo articolo...
domenica 29 marzo 2009
sabato 28 marzo 2009
COSA FA il Technical Writer ?
Proviamo a rispondere a questa domanda delineando le diverse parti di un puzzle molto interessante.
Nell’accezione più schematica, il TW si occupa di scrivere manuali.
Questa prima indicazione, così formulata, potrebbe suonare estremamente riduttiva.
In realtà il TW è il tramite tra il prodotto e l’utilizzatore del medesimo.
Deve rendere comprensibile ciò che non lo è, quindi scrive per spiegare.
Si pone dalla parte dell’utilizzatore, usando il linguaggio più opportuno per spiegare il funzionamento di un software o di una macchina.
Alcuni dei prodotti editoriali più comuni realizzati dal TW possono essere elencati di seguito:
… e altro ancora.
Ma per ognuno di questi prodotti, il TW applica uno schema di lavoro rigido e univoco o, nell’accezione migliore, “ben ingegnerizzato”… oppure deve adottare una strategia flessibile ed adattativa rispetto al contesto?
In altri termini, come si procede nella scrittura di un manuale ?
Pensando alla risposta migliore da dare a questa domanda, mi viene in mente un quadro di Mondrian, un insieme di rettangoli colorati, di diversa dimensione, ben distinti, che si compongono nelle modalità più diverse, a costituire un tutto organico, geometrico e cromaticamente armonico.
Proviamo a citare almeno le componenti principali di questo processo, sperando di riuscire a ricomporre un quadro convincente.
Leggi questo articolo...
Nell’accezione più schematica, il TW si occupa di scrivere manuali.
Questa prima indicazione, così formulata, potrebbe suonare estremamente riduttiva.
In realtà il TW è il tramite tra il prodotto e l’utilizzatore del medesimo.
Deve rendere comprensibile ciò che non lo è, quindi scrive per spiegare.
Si pone dalla parte dell’utilizzatore, usando il linguaggio più opportuno per spiegare il funzionamento di un software o di una macchina.
Alcuni dei prodotti editoriali più comuni realizzati dal TW possono essere elencati di seguito:
- il libretto di istruzioni per un elettrodomestico
- il manuale d’installazione di un prodotto software
- la guida alla manutenzione di un’automobile
- la newsletter che informa i clienti sull’evoluzione dei prodotti
- la quick reference per usare il telefonino
- il manuale utente di un programma software
- il documento di collaudo di un’architettura hardware
- il manuale API di una libreria software, finalizzato agli sviluppatori
- la scheda tecnica di un prodotto
- l'help online contestuale ad un’applicazione software
- la check-list per l’analisi dei guasti di un aereoplano
- i contenuti del sito aziendale
… e altro ancora.
Ma per ognuno di questi prodotti, il TW applica uno schema di lavoro rigido e univoco o, nell’accezione migliore, “ben ingegnerizzato”… oppure deve adottare una strategia flessibile ed adattativa rispetto al contesto?
In altri termini, come si procede nella scrittura di un manuale ?
Pensando alla risposta migliore da dare a questa domanda, mi viene in mente un quadro di Mondrian, un insieme di rettangoli colorati, di diversa dimensione, ben distinti, che si compongono nelle modalità più diverse, a costituire un tutto organico, geometrico e cromaticamente armonico.
Proviamo a citare almeno le componenti principali di questo processo, sperando di riuscire a ricomporre un quadro convincente.
Categoria:
Il mestiere del TW
sabato 14 marzo 2009
Soluzioni: uso degli elenchi.
Una delle situazioni più tipiche che mi è capitato di riscontrare nei documenti tecnici scritti in modo poco accorto, consiste nello scarso utilizzo degli elenchi (puntati e/o numerati) laddove sarebbero utili e necessari.
Consideriamo l'esempio seguente:
"...attraverso la console degli eventi è possibile controllare l'utente che ha effettuato una certa operazione, l'ora in cui è stata effettuata, il suo ruolo operativo registrato nel sistema, il dispositivo sui cui è stata effettuata, l'insieme degli eventi che sono stati scatenati dall'operazione, i dati coinvolti, le eventuali notifiche configurate..."
Che cosa abbiamo appena letto?
Niente di complicato... un semplice "elenco".
Un elenco di concetti, esattamente un elenco delle funzionalità accessibili attraverso una fantomatica "console degli eventi".
E allora perchè non lo scriviamo IN FORMA DI ELENCO ?
"...attraverso la console degli eventi è possibile controllare:
La differenza non è trascurabile.
Presentare in maniera banalmente descrittiva un set d'informazioni che, strutturalmente, identificano un elenco, costringe il lettore a ricostruire, nella sua testa, la struttura dell'elenco, inducendolo ad un inutile esercizio che lo distrae dal nocciolo della comunicazione.
Non è l'esempio più cattivo che potevo fare... ho visto elenchi di concetti/oggetti che si dipanavano su una dozzina di righe... in genere già alla sesta riga l'attenzione del lettore viene messa a dura prova.
Ma a questo punto dobbiamo fare un ulteriore distinzione tra "elenchi puntati" ed "elenchi numerati".
Nell'esempio precedente abbiamo usato un elenco puntato, perchè le informazioni presentate costituiscono "un insieme non ordinato"; che significa ?
Significa che modificare la posizione di uno più items dell'elenco, non modifica il contenuto della comunicazione.
Ma ora consideriamo un'altro esempio:
"...
1. Selezionare l’evento in errore più antico tra quelli prodotti.
2. Ricostruire la causa dell’errore in base agli indizi disponibili.
3. Sanare l’evento in base a quanto ricostruito.
4. Riavviare il Motore degli Eventi al fine di rielaborare l’evento.
5. Se l’evento va ancora in errore, è necessario ritornare al punto 2.
..."
E' evidente che, in questo caso, modificando l'ordine dei concetti, verrebbe meno il senso della comunicazione.
L'elenco numerato DEVE ESSERE SEMPRE utilizzato quando tra un insieme di oggetti/concetti esiste una relazione di ordinamento
che determina la semantica dell'elenco.
Leggi questo articolo...
Consideriamo l'esempio seguente:
"...attraverso la console degli eventi è possibile controllare l'utente che ha effettuato una certa operazione, l'ora in cui è stata effettuata, il suo ruolo operativo registrato nel sistema, il dispositivo sui cui è stata effettuata, l'insieme degli eventi che sono stati scatenati dall'operazione, i dati coinvolti, le eventuali notifiche configurate..."
Che cosa abbiamo appena letto?
Niente di complicato... un semplice "elenco".
Un elenco di concetti, esattamente un elenco delle funzionalità accessibili attraverso una fantomatica "console degli eventi".
E allora perchè non lo scriviamo IN FORMA DI ELENCO ?
"...attraverso la console degli eventi è possibile controllare:
- l'utente che ha effettuato una certa operazione;
- l'ora in cui è stata effettuata;
- il suo ruolo operativo registrato nel sistema;
- il dispositivo sui cui è stata effettuata;
- l'insieme degli eventi che sono stati scatenati dall'operazione
- i dati coinvolti;
- le eventuali notifiche configurate.
La differenza non è trascurabile.
Presentare in maniera banalmente descrittiva un set d'informazioni che, strutturalmente, identificano un elenco, costringe il lettore a ricostruire, nella sua testa, la struttura dell'elenco, inducendolo ad un inutile esercizio che lo distrae dal nocciolo della comunicazione.
Non è l'esempio più cattivo che potevo fare... ho visto elenchi di concetti/oggetti che si dipanavano su una dozzina di righe... in genere già alla sesta riga l'attenzione del lettore viene messa a dura prova.
Ma a questo punto dobbiamo fare un ulteriore distinzione tra "elenchi puntati" ed "elenchi numerati".
Nell'esempio precedente abbiamo usato un elenco puntato, perchè le informazioni presentate costituiscono "un insieme non ordinato"; che significa ?
Significa che modificare la posizione di uno più items dell'elenco, non modifica il contenuto della comunicazione.
Ma ora consideriamo un'altro esempio:
"...
1. Selezionare l’evento in errore più antico tra quelli prodotti.
2. Ricostruire la causa dell’errore in base agli indizi disponibili.
3. Sanare l’evento in base a quanto ricostruito.
4. Riavviare il Motore degli Eventi al fine di rielaborare l’evento.
5. Se l’evento va ancora in errore, è necessario ritornare al punto 2.
..."
E' evidente che, in questo caso, modificando l'ordine dei concetti, verrebbe meno il senso della comunicazione.
L'elenco numerato DEVE ESSERE SEMPRE utilizzato quando tra un insieme di oggetti/concetti esiste una relazione di ordinamento
che determina la semantica dell'elenco.
Categoria:
Soluzioni per la scrittura
venerdì 13 marzo 2009
CHI E' il Technical Writer ?
CHI E'... e COSA FA... il Technical Writer?
Sempifichiamo... iniziamo dal CHI E'. Per rispondere a questa domanda, ci si trova a dover superare ostacoli di non poco conto.
Il primo riguarda la “bassa densità” di questa figura nel panorama professionale italiano, dove spesso la figura del redattore tecnico è considerata erroneamente come una figura professionale di serie B.
Il nostro paese non riveste il ruolo di leader nella produzione di tecnologie innovative e di prodotti incentrati su di esse.
Il numero molto limitato, rispetto al mondo anglosassone o asiatico, di aziende che realizzano “prodotti”, influenza negativamente la promozione di figure specializzate nella redazione di documentazione tecnica.
Il secondo è relativo al problema della “formazione” del TW, che non è banalmente schematizzabile. Nei paesi anglosassoni ci sono scuole e corsi universitari per insegnare a scrivere documentazione tecnica; in Italia da alcuni anni, se pur lentamente, si stanno diffondendo alcuni corsi, di solito incastonati nel piano di studi delle facoltà di Lettere, Ingegneria o Scienze della Comunicazione.
Tuttavia siamo ancora lontani da un percorso formativo completo, in grado di nutrire un profilo versatile come quello che deve caratterizzare un TW.
Nella maggiorparte dei casi, il TW si forma "sul campo", all'interno della realtà aziendale in cui ha origine l'esigenza di produrre documentazione tecnica.
Generalmente, si parte da una buona base tecnica, legata all’ambito specifico in cui ci si trova ad operare; scrivere un manuale che descrive un'architetture hardware/software è un compito che può, in teoria, essere affidato anche ad un profano, ma è abbastanza probabile che un ingegnere informatico possa operare in tal senso con maggior cognizione di causa.
Tuttavia, molti TW "guru" italiani denotano una formazione di tipo letterario-umanistica.
Da questi elementi, concludiamo che la tipologia di formazione non è vincolante.
La formazione è solo uno scheletro, che poi deve essere rivestito attraverso la “pratica” che deve rivestire di senso la necessaria “grammatica”.
Quindi quali altri elementi entrano in gioco ? Se si ha la ventura di lavorare in un'azienda che realizza prodotti, allora ci si trova in una posizione di vantaggio rispetto alla possibilità di accedere a questa professione; Darwin direbbe che "l'ambiente favorisce l'evoluzione della specie".
Ma poi è necessaria una "predisposizione" soggettiva.
Passione per la letteratura e per la scrittura, curiosità, interesse per la comunicazione e per gli aspetti psicologici ad essa associati, capacità di interagire con tutti coloro che possono fornirci le informazioni necessarie, fantasia, elasticità mentale, creatività e precisione, capacità di visione, conoscenze tecniche e redazionali, velocità di apprendimento... e forse altro che ora non mi sovviene. E tutti questi elementi miscelati in percentuale ignota.
E poi ci vuole "l'occasione"... perchè finchè non si viene messi alla prova, tutte le qualità sopracitate, quandanche presenti, non avranno modo di manifestarsi.
A me è capitato tutto questo: la formazione tecnica, l'ambiente, la predisposizione, l'occasione. Direi che per ora possiamo fermarci qui, ma nei prossimi post mi riprometto di approfondire diversi altri temi inerenti alla professione del TW.
Leggi questo articolo...
Sempifichiamo... iniziamo dal CHI E'. Per rispondere a questa domanda, ci si trova a dover superare ostacoli di non poco conto.
Il primo riguarda la “bassa densità” di questa figura nel panorama professionale italiano, dove spesso la figura del redattore tecnico è considerata erroneamente come una figura professionale di serie B.
Il nostro paese non riveste il ruolo di leader nella produzione di tecnologie innovative e di prodotti incentrati su di esse.
Il numero molto limitato, rispetto al mondo anglosassone o asiatico, di aziende che realizzano “prodotti”, influenza negativamente la promozione di figure specializzate nella redazione di documentazione tecnica.
Il secondo è relativo al problema della “formazione” del TW, che non è banalmente schematizzabile. Nei paesi anglosassoni ci sono scuole e corsi universitari per insegnare a scrivere documentazione tecnica; in Italia da alcuni anni, se pur lentamente, si stanno diffondendo alcuni corsi, di solito incastonati nel piano di studi delle facoltà di Lettere, Ingegneria o Scienze della Comunicazione.
Tuttavia siamo ancora lontani da un percorso formativo completo, in grado di nutrire un profilo versatile come quello che deve caratterizzare un TW.
Nella maggiorparte dei casi, il TW si forma "sul campo", all'interno della realtà aziendale in cui ha origine l'esigenza di produrre documentazione tecnica.
Generalmente, si parte da una buona base tecnica, legata all’ambito specifico in cui ci si trova ad operare; scrivere un manuale che descrive un'architetture hardware/software è un compito che può, in teoria, essere affidato anche ad un profano, ma è abbastanza probabile che un ingegnere informatico possa operare in tal senso con maggior cognizione di causa.
Tuttavia, molti TW "guru" italiani denotano una formazione di tipo letterario-umanistica.
Da questi elementi, concludiamo che la tipologia di formazione non è vincolante.
La formazione è solo uno scheletro, che poi deve essere rivestito attraverso la “pratica” che deve rivestire di senso la necessaria “grammatica”.
Quindi quali altri elementi entrano in gioco ? Se si ha la ventura di lavorare in un'azienda che realizza prodotti, allora ci si trova in una posizione di vantaggio rispetto alla possibilità di accedere a questa professione; Darwin direbbe che "l'ambiente favorisce l'evoluzione della specie".
Ma poi è necessaria una "predisposizione" soggettiva.
Passione per la letteratura e per la scrittura, curiosità, interesse per la comunicazione e per gli aspetti psicologici ad essa associati, capacità di interagire con tutti coloro che possono fornirci le informazioni necessarie, fantasia, elasticità mentale, creatività e precisione, capacità di visione, conoscenze tecniche e redazionali, velocità di apprendimento... e forse altro che ora non mi sovviene. E tutti questi elementi miscelati in percentuale ignota.
E poi ci vuole "l'occasione"... perchè finchè non si viene messi alla prova, tutte le qualità sopracitate, quandanche presenti, non avranno modo di manifestarsi.
A me è capitato tutto questo: la formazione tecnica, l'ambiente, la predisposizione, l'occasione. Direi che per ora possiamo fermarci qui, ma nei prossimi post mi riprometto di approfondire diversi altri temi inerenti alla professione del TW.
Leggi questo articolo...
Categoria:
Il mestiere del TW
lunedì 2 marzo 2009
Soluzioni: uso delle tabelle.
Nella letteratura tecnica, l'uso delle tabelle può essere particolarmente efficace per comunicare le relazioni che intercorrono tra due o più entità.
Non siamo generalmente allenati ad esaminare una situazione, un contesto, una descrizione e a riconoscere la struttura relazionale dei diversi elementi in essa coinvolti.
Di contro, è molto comune trovarsi a leggere una descrizione estesa di un'insieme di relazioni che spesso conduce il lettore in un gorgo in cui annegare può sembrare il minore dei mali!
Un esempio? Eccolo:
"... l'architettura proposta è caratterizzata da 3 parametri (A, B e C); nel caso in cui la piattaforma si trovi nello stato di sviluppo, la terna di parametri assume i valori 1, 1 e 0. Se si trova nello stato di collaudo, i parametri valgono 1, 0 e 0.
Quando la piattaforma viene portata nello stato di esercizio, i tre parametri vengono posti a 1..."
Si può fare di meglio ? Si... con una tabella!
Ma ora esaminiamo un secondo esempio ...eccolo:
"... le statistiche ci indicano che, ad un anno dal conseguimento della laurea, i laureati in Ingegneria che ottengono un contratto a tempo determinato sono il 57% ed un contratto a tempo indeterminato è appannaggio del 29%.
A due anni le percentuali si modificano passando, rispettivamente, al 61% e al 32%. A tre anni, siamo al 55% e al 41%. Come vanno le cose per i Fisici ? Ad un anno, 39% e 7%; a due anni 59% e 18%; a tre anni, 45% e 48%.
Per i Chimici, dopo un anno, 18% e 5%; dopo due, 39% e 22%; dopo 3 anni, 40% e 50%.
E come vanno le cose per le facoltà umanistiche ? Prendiamo in esame Scienze Politiche, Giurisprudenza e Lettere.
Per Scienze Politiche, ad una anno della laurea le percentuali sono sconfortanti: il 20% riesce ad ottenere un contrato a tempo determinto e soli il 2% a tempo indeterminato.
A due anni, le percentali salgono di poco, 28% e 8%.
Al terzo anno, 33% e 15%.
Per Giurisprudenza... "
Che ne dite ? Io mi sono già perso... E L'HO SCRITTO IO!
Anche qui, una tabella sarebbe in grado di coniugare sintesi e semantica, guidando l'occhio del lettore a cogliere i dati essenziali, senza disperderli in un periodo iper strutturato.
I due esempi proposti servono a focalizzare un'idea che ritengo fondamentale: non si deve MAI costringere il lettore ad uno sforzo superfluo, rispetto a quello strettamente necessario, per comprendere il concetto che vogliamo comunicare.
In altri termini... SEMPLICITA'!
Questa idea chiave, che a me sta molto a cuore, verrà spesso riproposta in questo blog e la ritroveremo anche nei post relativi all'uso dele immagini.
Scrivere "complicato" non è sinonimo di maggior cultura o di fine intelligenza, anzi.
Un TW deve trasmettere concetti spesso complessi nel modo più chiaro e diretto possibile, senza stravolgere i contenuti ma proponendoli in una forma essenziale e completa... e una tabella è spesso una buona alleata!
Leggi questo articolo...
Non siamo generalmente allenati ad esaminare una situazione, un contesto, una descrizione e a riconoscere la struttura relazionale dei diversi elementi in essa coinvolti.
Di contro, è molto comune trovarsi a leggere una descrizione estesa di un'insieme di relazioni che spesso conduce il lettore in un gorgo in cui annegare può sembrare il minore dei mali!
Un esempio? Eccolo:
"... l'architettura proposta è caratterizzata da 3 parametri (A, B e C); nel caso in cui la piattaforma si trovi nello stato di sviluppo, la terna di parametri assume i valori 1, 1 e 0. Se si trova nello stato di collaudo, i parametri valgono 1, 0 e 0.
Quando la piattaforma viene portata nello stato di esercizio, i tre parametri vengono posti a 1..."
Si può fare di meglio ? Si... con una tabella!
Ma ora esaminiamo un secondo esempio ...eccolo:
"... le statistiche ci indicano che, ad un anno dal conseguimento della laurea, i laureati in Ingegneria che ottengono un contratto a tempo determinato sono il 57% ed un contratto a tempo indeterminato è appannaggio del 29%.
A due anni le percentuali si modificano passando, rispettivamente, al 61% e al 32%. A tre anni, siamo al 55% e al 41%. Come vanno le cose per i Fisici ? Ad un anno, 39% e 7%; a due anni 59% e 18%; a tre anni, 45% e 48%.
Per i Chimici, dopo un anno, 18% e 5%; dopo due, 39% e 22%; dopo 3 anni, 40% e 50%.
E come vanno le cose per le facoltà umanistiche ? Prendiamo in esame Scienze Politiche, Giurisprudenza e Lettere.
Per Scienze Politiche, ad una anno della laurea le percentuali sono sconfortanti: il 20% riesce ad ottenere un contrato a tempo determinto e soli il 2% a tempo indeterminato.
A due anni, le percentali salgono di poco, 28% e 8%.
Al terzo anno, 33% e 15%.
Per Giurisprudenza... "
Che ne dite ? Io mi sono già perso... E L'HO SCRITTO IO!
Anche qui, una tabella sarebbe in grado di coniugare sintesi e semantica, guidando l'occhio del lettore a cogliere i dati essenziali, senza disperderli in un periodo iper strutturato.
I due esempi proposti servono a focalizzare un'idea che ritengo fondamentale: non si deve MAI costringere il lettore ad uno sforzo superfluo, rispetto a quello strettamente necessario, per comprendere il concetto che vogliamo comunicare.
In altri termini... SEMPLICITA'!
Questa idea chiave, che a me sta molto a cuore, verrà spesso riproposta in questo blog e la ritroveremo anche nei post relativi all'uso dele immagini.
Scrivere "complicato" non è sinonimo di maggior cultura o di fine intelligenza, anzi.
Un TW deve trasmettere concetti spesso complessi nel modo più chiaro e diretto possibile, senza stravolgere i contenuti ma proponendoli in una forma essenziale e completa... e una tabella è spesso una buona alleata!
Leggi questo articolo...
Categoria:
Soluzioni per la scrittura
Iscriviti a:
Post (Atom)