cosa fa un technical writer?

Visto che periodicamente mi capita di dover spiegare in che cosa consiste il mio lavoro e questa storia va avanti da oltre 6 anni, ho pensato di creare questa paginetta per rendere un servizio utile alla categoria professionale  (e all’umanità intera, a dire il vero). Prego!

Che manuale sarebbe senza una TOC?

La TOC (Table of Contents) non è altro che l’indice dei capitoli, da non confondersi con l’Index, che è invece l’indice analitico.

5 cose che avreste sempre voluto sapere sui technical writer
(ma non avete mai osato chiedere)

  • Come hai fatto a diventare technical writer?
    Molti intraprendono questa professione per qualche strana coincidenza della vita, pochissimi invece studiano appositamente per diventare redattori di contenuti tecnici. Sono disposta a scommettere che qualunque altra risposta riceverete è un’elaborata menzogna. (“Ho sempre amato confrontarmi con le problematiche dell’utente, sin da quando la suora mi spaccava i maroni per farsi spiegare come stampare le brochure dell’oratorio utilizzando un print server remoto.”) Nel mio caso, la storia è piuttosto lunga… se vi interessa, scrivetemi o commentate qui sotto e ve la racconto!
  • Non ho mai lavorato con un technical writer. Cosa devo aspettarmi?
    Un buon technical writer tende a stare alle costole di tutte le persone che detengono informazioni sul prodotto (gli SMEs, o Subject Matter Experts), come ad esempio sviluppatori, product managers, project managers, information architects, help desk, pre-sales, e cosi via, e a martellarli con richieste di chiarimenti, documenti, mock-up, spiegazioni, esempi, use cases, business cases, specifiche e altro. Affronta il problema dal punto di vista dell’utente finale, a cui  molto spesso non servono tutti i dettagli forniti dagli SMEs (“Il campo del nome accetta come valore una stringa di max 20 caratteri unicode in formato UTF-8”) quindi non restateci male se molti di questi dettagli non finiranno nel manuale!
  • È davvero così importante il manuale?
    OK ammettiamolo, nessuno legge il manuale, a meno di non essere alla disperata ricerca di informazioni chiave per risolvere un problema o fare qualcosa che non si riesce a dedurre intuitivamente dall’interfaccia. (Incidentalmente, migliorare la UI è uno dei migliori investimenti che si possano fare per il successo del prodotto in generale…) Per questo motivo, se il manuale / la guida online / l’help sono di qualità scadente, è quasi meglio non averli ed evitare così il rischio di far imbestialire l’utente finale e ricevere un giudizio complessivamente negativo. Se invece la documentazione del software è semplice da utilizzare, completa e dettagliata, si risparmiano chiamate e email al servizio clienti, gli utenti sono soddisfatti e la recensione finale del prodotto (e dell’azienda) sarà decisamente positiva.
  • Come hai potuto metterci un mese a creare una guida di 10 pagine? 
    In soldoni, ci vuole molto più tempo a creare istruzioni succinte, usabili ed effettivamente utili che ad elencare tutti i dettagli possibili e immaginabili e descrivere minuziosamente l’interfaccia, soprattutto per prodotti software complessi. Anzi, più il software è complesso e più tempo ci vorrà a creare della documentazione efficace e ridotta all’osso.
  • Ah, fai lo scrittore? Come ti invidio. 
    Non fatevi ingannare dal nome: i technical writer non sono scrittori nel senso di romanzieri o saggisti. In molte situazioni, a dire il vero, scrivere è una parte marginale del lavoro di un comunicatore tecnico, che passa ore e ore a pianificare, leggere, tracciare, collaborare, coordinare, formulare domande e decifrare risposte… Non c’è molto da invidiare :-)

“When I grow up I want to be a tech writer!” (photo credits)

Patti chiari, amicizia lunga
(ovvero, che cosa fa e che cosa non fa un technical writer)

Il ruolo del technical writer è quello di comunicare informazioni tecniche complesse utilizzando un linguaggio chiaro, semplice, conciso e – soprattutto – adatto all’utente finale, scegliendo il formato più appropriato (per esempio, una scheda tecnica da appiccicare su una lavatrice piuttosto che manuale di istruzioni di una macchina fotografica professionale).

Come è facile immaginare, non esistono “taglie uniche” nella documentazione, e come un buon servizio di sartoria prima di arrivare al prodotto finale bisogna necessariamente fare tutti i passi intermedi, dalla scelta del sarto ai ritocchi finali:

  1. incontrare il cliente e raccogliere i requisiti (prendere le misure di chi indosserà il vestito)
  2. definire la strategia più adatta al caso (scegliere stoffa e modello)
  3. fissare una tabella di marcia (mettersi d’accordo sulle date per la prova e la consegna)
  4. interagire con chi conosce meglio il prodotto per ottenere tutte le informazioni necessarie (chiedere chiarimenti al committente su dettagli poco chiari del modello)
  5. effettuare delle verifiche intermedie, per accertarsi di essere sulla strada giusta (invitare il cliente per una prova del vestito prima delle cuciture e rifiniture definitive)
  6. pubblicare la documentazione nei formati stabiliti (consegnare il vestito confezionato secondo gli accordi)
  7. mantenere aperto il canale di comunicazione col cliente per apportare future modifiche o correzioni (dare la possibilità al cliente di tornare in sartoria per eventuali ritocchi)

Uscendo dalla metafora, ecco alcune delle attività tipiche di un technical writer:

  • analisi dei requisiti e definizione delle diverse audience
  • pianificazione delle attività e comunicazione con il team e gli SMEs
  • studio e prova del prodotto (o nuove funzionalità) da documentare
  • redazione dei contenuti utilizzando vari tool (per es. Word, FrameMaker, Flare, RoboHelp, XML/DocBook, DITA, Confluence o altro wiki, Captivate, Photoshop, …) e applicando gli stili e le convenzioni in uso (preferibilmente, raggruppati e descritti in una style guide)
  • revisione dei contenuti da parte degli SMEs e della lingua (grammatica, ortografia, stile, …) da parte dell’editor
  • pubblicazione dei contenuti nel formato concordato e più adatto (PDF, HTML, help all’interno del prodotto, video tutorial, …)
  • chiusura e archiviazione dei progetti completati
If you want them to RTFM, make a better FM
Kathy Sierra, you have a point… and BTW, nice blog post!

Non si tratta solo di  scrivere, organizzare e pubblicare. A seconda del committente, delle responsabilità e del tempo a disposizione, le attività di un technical writer comprendono anche:

  • ricerca di nuovi tool, linguaggi e metodi per semplificare e velocizzare il lavoro o per strutturare meglio i contenuti e pubblicarli in molteplici formati, se possibile in modo automatico
  • aggiornamento professionale (corsi, letture, conferenze)
  • training e supporto di altri technical writer
  • partecipazione ai meeting del team di sviluppo (scrum meetings, scrum of scrums, riunioni preliminari, retrospettive, …)
  • analisi dell’usabilità del prodotto e della UI, compresi test di QA
  • mantenimento di buone relazioni con tutte le persone coinvolte nel processo di pianificazione, sviluppo, test e rilascio del software, perché è meglio oliare gli ingranaggi prima che si intoppino

Il technical writer non è un jolly. Probabilmente potrebbe aiutarvi con le seguenti cose, a seconda delle sue capacità ed esperienze, ma è un po’ come chiedere a un pasticcere di farvi una pizza, insomma. Potrebbe andarvi bene, ma potrebbe anche andarvi male.

  • traduzioni (per quello ci sono i traduttori)
  • redazione di specifiche tecniche e funzionali del prodotto (per quello ci sono i product manager, gli architect e i product definition specialist)
  • correzione di bozze (per quello ci sono gli editor)
  • redazione di contenuti istituzionali (per quello ci sono i copywriter, web editor e personale di marketing) 

You say information developer, I say technical writer

Ecco qui una rassegna dei vari job title che potreste incontrare nell’ambito di questa professione, in ordine sparso: technical writer, information developer, information specialist, technical communicator, technical communication specialist, technical author, documentation manager, documentation specialist, knowledge manager, technical editor, scrittore tecnico, redattore tecnico.

Attualmente sul mio contratto c’è scritto rédacteur technique. Voilà.

Quanto alla job description, eccovi alcune idee sulle caratteristiche ideali da ricercare in un technical writer.

Percorso accademico e professionale:

  • laurea o esperienza in ambito umanistico (lettere, lingue, comunicazione,  giornalismo, traduzione, …) come pure in ambito scientifico (ingegneria, informatica o campo specialistico in cui opera l’azienda, per es. cloud computing)
  • ruolo precedente come technical writer in un gruppo già avviato e strutturato
  • esperienza come analista, ricerca & sviluppo, help desk, QA, oppure marketing e comunicazione, product management, community manager

Competenze informatiche (software e linguaggi):

  • dimestichezza con i vari tool usati per produrre la documentazione (variabili a seconda dell’azienda e del progetto: Word, FrameMaker, Flare, RoboHelp, XML/DocBook, DITA, Confluence o altro wiki, Captivate, Photoshop, e molti altri…)
  • buona conoscenza di HTML, CSS e web design
  • comprensione delle dinamiche e delle logiche della programmazione (script, linguaggi formali, programmazione a oggetti, etc…)

 Caratteristiche personali:

  • ottime capacità di ascolto e analisi delle informazioni
  • ottime capacità di esprimere e rielaborare concetti complessi in modo semplice, utilizzando un linguaggio adatto al lettore
  • ottime capacità di scrittura nella lingua richiesta (grammatica, ortografia, vocabolario, diversi registri, diversi stili, …)
  • buone competenze tecniche per comprendere al meglio i prodotti da documentare
  • disponibilità a lavorare in team, condividendo il lavoro con altri tech writer e collaborando con gli SMEs e gli altri ruoli coinvolti nel processo di documentazione
  • precisione e attenzione ai dettagli
  • affidabilità e responsabilità
  • immaginazione e creatività per affrontare i problemi da punti di vista diversi
  • facilità di apprendimento (nuovi prodotti, nuovi standard, nuovi formati, etc.)

Queste, naturalmente, sono solo delle idee… anche le caratteristiche del candidato ideale, come quelle della documentazione ideale, vanno ritagliate su misura in base all’azienda, al prodotto, agli strumenti in uso, ai requisiti, al budget, … Buona fortuna quindi!

La vita segreta di un technical writer

Per la mia esperienza (e per amore della generalizzazione) tutti i technical writer si possono descrivere facendo un mix  delle seguenti 4 categorie. Esistono anche esemplari di categoria pura, ma fortunatamente sono rari.


Ken: “Technical writing is so passé.”
Barbie: “Yes, darling. We should get into digital marketing.”

1. Lo scriba

Come uno scriba ai tempi dell’antico Egitto o un amanuense del XIII secolo dopo Cristo, scrive sotto dettatura, ricopia, riscrive, esegue gli ordini senza esulare mai dallo scope dei suoi task. Ha paura delle sfide e dell’improvvisazione, non è minimamente interessato alle novità del settore. Vuole solo avere un bel titolo sul CV e portare a casa la pagnotta.

Pregi: fa tutto quello che viene chiesto, esattamente come gli è stato chiesto.

Difetti: se non  vi spiegate bene, non otterrete un bel nulla.

2. Il fossile

Ha iniziato a fare questo lavoro quando il Fortran era ancora in gran voga, principalmente perché era l’unico in grado di scrivere in inglese e/o digitare su una tastiera. Nel corso degli anni ha imparato a decifrare le specifiche tecniche e i design document del software e non sente la necessità di confrontarsi con il team di sviluppo. Pensa che la sua età anagrafica sia ragione sufficiente per liquidare sbrigativamente le idee dei technical writer più giovani. Non usa Facebook né Twitter. Talvolta non ha nemmeno un cellulare.

Pregi: ottima scelta se dovete documentare dei mainframe, software arcaico, UI non social, non grafiche e non moderne. Molto indicato anche se sperate di cavarvela con un mega zippone di specifiche techniche e nessun mock-up.

Difetti: non è in grado di elaborare pensieri compatibili con il software e gli utenti dei tempi moderni.

3. Il niubbo

Per qualche motivo incognito, vede la professione di technical writer come una gallina dalle uova d’oro. Una o più di queste affermazioni lo descrivono perfettamente:

  • non ha esperienza di sviluppo software
  • non ha dimestichezza con le problematiche più comuni del mestiere (da come strutturare i contenuti al formato migliore per pubblicarli)
  • non ha certificazioni pertinenti (lingue, comunicazione, ingegneria informatica, …)
  • non ha abilità linguistiche particolarmente avanzate, né in italiano né in inglese
  • sfoggia le sue presunte competenze senza però fornire prove concrete (“ottima conoscenza pacchetto MS Office”, “inglese fluente”, etc…)

Pregi: vi sembrerà un vero affare dato che – sulla carta – sa fare un mucchio di cose e probabilmente riuscirete ad ingaggiarlo per una cifra tutto sommato contenuta.

Difetti: quando vi sveglierete dallo stato di trance indotto dal niubbo abile nel self-marketing, sarà ormai troppo tardi e vi ritroverete con un help online che assomiglia a quello di Volunia.

4. L’über technical writer

Appassionatissimo di scrittura e tecnologia, mastica pane e XML per colazione e si rilassa partecipando attivamente ai forum di discussione online sull’argomento. È sempre al corrente di tutte le novità del settore, i trend, le best practice, i software più gettonati. È preciso nella pianificazione ed efficace e rapido nell’esecuzione, ha un talento per le relazioni sociali con gli stakeholder (dal programmatore geek al product manager fighetto) e capisce ogni cosa al volo. Partecipa alle conferenze della STC proponendo seminari che fanno il tutto esaurito. Ha un blog autorevole di comunicazione tecnica e scrittura e 150mila follower su Twitter.

Pregi: è un mostro di bravura, saggezza, intelligenza, tatto e contribuirà a migliorare sensibilmente il vostro prodotto, non solo per quanto riguarda la documentazione in senso stretto.

Difetti: vi sarà difficile stargli dietro. Se non vi fidate della sua competenza e cercate di imbrigliarlo in regolamenti e processi non ottimali, mettendo in dubbio le sue scelte (lessicali, grammaticali, di formato, metodo di lavoro, etc.) gli tarperete le ali e otterrete risultati subottimali.


“Hi, I am your über tech writer babe, how can I help you today?”

Letture consigliate

Qui di seguito trovate dei link ad articoli in cui altri hanno cercato di definire il ruolo del redattore di manuali tecnici, AKA technical writer, in italiano. Come vedrete le interpretazioni sono a volte piuttosto distanti, anche se fortunatamente ritroviamo ovunque i punti chiave della professione.

Suggeritene pure altri se ne conoscete e li aggiungerò alla lista!

Un’interessante intervista sul blog di una scrittrice di professione
http://www.mestierediscrivere.com/index.php/articolo/technicalwriting

I requisiti base del mestiere sul sito di una società che fornisce consulenze nel campo
http://www.writec.com/profili.asp

Un dettagliato rapporto sul lavoro dei technical writer a cura del Dipartimento del Lavoro statunitense (in inglese)
http://www.bls.gov/ooh/Media-and-Communication/Technical-writers.htm

Repertorio delle professioni legate alla comunicazione, Università di Padova
http://www.comunicazione.lettere.unipd.it/osservatorio/aggiornamenti2007.php#writer

Il blog di un technical writer italiano
http://artigianodibabele.blogspot.fr/2008/12/mi-presento.html

Un luuuungo articolo su Apogeo Online (taluni son pagati a battuta, parrebbe)
http://www.apogeonline.com/webzine/2005/09/28/01/200509280101

La voce italiana su Wikipedia
http://it.wikipedia.org/wiki/Technical_writer

Un blog che parla di scrittura mettendo la virgola tra il soggetto e il verbo (#fail)
http://www.technicalwriter.it/2012/04/18/wikis-il-futuro-della-documentazione/


“Documenting software for the travel industry
in the wonderful setting of the Côte d’Azur
is so demanding.”

6 Comments

  1. a Says:

    Ho letto con gran gusto :*
    T’abbraccio bella!

  2. Giulia Says:

    Grazie cara!! Ricambio l’abbraccio <3

  3. Stefano Says:

    Ciao ho letto il tuo interessante articolo, volevo chiederti se conosci il software Adobe Framemaker che hai menzionato sopra, sono un manualista alle prime armi e avrei bisogno di qualche dritta :)

  4. Giulia Says:

    Ciao! Certo, chiedi pure e se riesco ti aiuto volentieri :)

  5. Stefano Says:

    Ti ho scritto una mail :)

  6. Alesatoredivirgole Says:

    Complimenti per l’articolo !

    Anch’io spesso mi trovo a dover spiegare “cosa faccio” … precisando però che NON sono uno scrittore !!!

    Come scritto in un recente post nel mio sgangherato blog, oggi sono paragonabile a quello che viene definito un “Solo Writer” con una formazione cocktail :-)

Leave a comment