Guide, FAQ e documenti: il mestiere del tech writer

L’esperienza del Team per la Trasformazione Digitale: cambiare il linguaggio della Pubblica Amministrazione, una frase alla volta

Tutti abbiamo bisogno di guide

Siamo costantemente alla ricerca di informazioni online: dalla ricetta per la torta alla più recente libreria di JavaScript, c’è sempre qualcosa che non sappiamo o un’informazione che ci manca.

È una situazione familiare: quando abbiamo un problema, il primo impulso è chiedere a un motore di ricerca. Formuliamo la nostra domanda con poche parole, scelte accuratamente. Se tutto va come previsto, troviamo la pagina che cercavamo, seguiamo i passaggi descritti e mettiamo in forno l’impasto (oppure pubblichiamo il nostro nuovo sito).

A volte però le cose non vanno come sperato e la guida che cercavamo non si rivela abbastanza chiara. Perdiamo tempo, ci arrabbiamo, tornando frustrati alle nostre attività senza aver risolto niente.

Il technical writer

Di recente abbiamo avviato un’attività di technical writing all’interno del progetto Docs Italia del Team per la Trasformazione Digitale. Il technical writer è la figura che sta a metà strada tra ciò che vogliamo ottenere e la nostra felicità. Letteralmente scrittore tecnico (o anche comunicatore tecnico, nell’accezione che ne dà Gianni Angelini nel suo libro), il technical writer ha il compito di capire i bisogni degli utenti e di scrivere guide che li aiutino nei loro compiti.

Tipicamente, I testi prodotti da un technical writer sono manuali di istruzioni per dispositivi o macchinari, manuali per pacchetti software, documentazione per API e così via. (No, la ricetta per la torta alle mele non rientra tra i compiti di un technical writer.)

I documenti scritti dai technical writer si possono dividere essenzialmente in due categorie.

• Documenti tecnici: hanno come destinatario il personale tecnico. Per esempio, la software house di un Comune che deve integrare SPID, il sistema pubblico di identità digitale, ha bisogno di una guida che aiuti i propri dipendenti a farlo passo dopo passo. In questo caso il linguaggio è tecnico e lo sforzo principale è, come dice il designer John Maeda, “sottrarre l’ovvio e aggiungere il significativo“: togliere tutto ciò che non serve, lasciare gli elementi che aiutano le persone a raggiungere il proprio scopo senza distrazioni, senza “rumore”.
• Guide di un prodotto: hanno lo scopo di descrivere il prodotto direttamente a chi lo userà e al personale dell’assistenza clienti. Per esempio, possiamo pensare alla sezione Domande Frequenti di un sito Internet, a supporto degli utenti. In questo caso la grande sfida è quella della divulgazione: si tratta di interpretare il prodotto pensando a come verrà usato dalle persone, piuttosto che alle sue funzionalità tecniche. Una delle tante cose a cui bisogna pensare è la capacità di creare una relazione di fiducia con gli utenti, mettendoli a proprio agio. E una delle chiavi della capacità di creare un rapporto di fiducia è la semplicità. Sempre secondo Maeda: “In simplicity we trust”.

In realtà, nell’ottica di aiutare gli utenti, la “guida” può spesso essere sostituita da una tabella, un diagramma, un’immagine o una qualsiasi combinazione di contenuti che possano essere utili allo scopo. In questo senso, spesso il lavoro di un technical writer si avvicina di più a quello di un designer di contenuti, o content designer, che a uno scrittore puro. I technical writer sono, infatti, il punto di incontro fra la tecnologia e gli utenti. A questo scopo, devono avere:

• competenze tecniche, ovvero essere in grado di capire la tecnologia che descrivono a un livello profondo;
• competenze di design, in particolare sul linguaggio e sulla user research, per poter comunicare al meglio le loro idee agli utenti.

Semplificare e immaginare

Due parole descrivono al meglio il lavoro del technical writer: semplificare e immaginare.

Semplificare è d’obbligo quando si vuole rendere accessibile un argomento complesso. L’idea è di rimuovere tutte le barriere che potrebbero impedire a chi legge un testo di comprenderne il significato.

Un primo ostacolo sono le frasi troppo lunghe o i termini troppo complessi. In questo caso, l’uso del plain language, ovvero un linguaggio semplice e chiaro, può aiutare. Alcune semplici regole sono indicate nel capitolo sul linguaggio delle Linee guida di design e proprio in queste settimane stiamo lavorando a una importante evoluzione di questa sezione, con maggiori informazioni e strumenti utili.

Un secondo problema sono i termini tecnici (spesso in inglese), conosciuti soltanto dagli addetti ai lavori. In questo caso, l’uso di questi termini è necessario per ragioni di precisione di linguaggio, ma il loro significato dovrebbe essere definito in un glossario allegato al documento.

Semplificare non significa rendere le cose banali, significa renderle più accessibili, per usare un noto adagio di GOV.UK.

Immaginare aiuta invece a capire cosa vogliono gli utenti, cosa cercano, qual è il loro scopo. Significa immaginare le azioni che compieranno e pianificare i contenuti in modo da agevolare la loro vita.

Semplificare e immaginare sono azioni strettamente legate: mettersi nei panni degli utenti significa immaginare quello che provano e pensano di fronte a una pagina. Immaginare le loro frustrazioni, per esempio, aiuta a pensare a possibili modi per semplificare le loro vite.

L’immaginazione non basta

L’immaginazione è importante, ma non basta. In primo luogo, i technical writer devono avere una forte competenza su come si scrive — e di come si legge — sul web: utilizzare correttamente i link, avere competenze SEO, saper titolare in modo efficace. Queste competenze sono riassunte nella sezione di Designers Italia dedicata ai contenuti.

In secondo luogo, i technical writer devono conoscere gli utenti a cui devono rivolgersi su una base oggettiva. Devono partecipare all’attività di user research, in alcuni casi saper condurre direttamente la ricerca e avere le competenze per analizzare tutti i tipi di dati disponibili sugli utenti per migliorare i documenti di cui si occupano. Per fare un esempio, nel progetto Docs Italia usiamo il sistema di web analytics Piwik/Matomo per sapere quante persone leggono determinati documenti, come e per quanto tempo. È importante sapere che parole usano per cercare i documenti online e confrontarle con quelle contenute nel testo, eventualmente per allineare le guide ai bisogni degli utenti.

Leggi anche: I dati che ci aiutano a capire i bisogni dei cittadini

Un altro strumento utile sono i cosiddetti test di usabilità. Questi aiutano a comprendere in che modo un utente interagisce con il prodotto (in questo caso il testo sulla pagina web) per portare a termine una mansione specifica. Le informazioni che si ottengono da questi esperimenti sono fondamentali per capire i punti deboli di una guida e i possibili modi per migliorarla.

Leggi anche: Test di usabilità: il kit di designers Italia

La rivoluzione è in atto

Docs Italia è il banco di prova in cui sperimentiamo queste idee, giorno dopo giorno. Il nostro obiettivo è quello di cambiare il linguaggio della Pubblica Amministrazione, a partire dai documenti amministrativi e dalla guide di progetto.

La rivoluzione di Docs Italia consiste nel mettere i cittadini al centro, partendo dal linguaggio a loro più vicino. E i technical writer sono proprio lo strumento di questo cambiamento.