Perché nessuno legge la documentazione?
Una documentazione ben progettata favorisce la sostenibilità: permette di non sprecare risorse, promuove l’efficienza, minimizza i consumi. E ci semplifica la vita, casomai sembrasse poco.
Grazie alle persone che hanno risposto ai sondaggi! A quanto pare una buona maggioranza apprezza le interviste: questo mi rallegra e mi fa venire un’ideuzza per il prossimo anno, ne parleremo.
L’11 ottobre ero a Bologna per Better Software, la conferenza Grusp dedicata alla sostenibilità del software. Insieme a
abbiamo parlato di come il linguaggio giochi un ruolo importante anche secondo questa prospettiva. Se vuoi un assaggio del nostro discorso puoi scaricare le slide.
Sulle parole: perché nessuno legge la documentazione?
Andrea è dal benzinaio: vuole verificare la pressione delle gomme della macchina. Ma quali erano i valori giusti? Era 2.2 per le ruote davanti e 2.0 dietro? O 2.4 e 2.2? Non lo ricorda, anche se l’ha fatto il mese scorso. Prende il manuale: dato che sono 496 pagine apre l’indice e cerca la sezione “Manutenzione del veicolo”, ma l’informazione non sembra essere lì. Torna all’indice e lo scorre più attentamente, cercando qualche indizio. Prova a vedere nella tabella con le specifiche tecniche del veicolo, e dopo aver scorso un paio di volte le righe finalmente trova l’informazione che cercava.
Teresa ha iniziato un nuovo lavoro: durante il suo primo giorno ha parlato con diversi colleghi che le hanno mostrato le procedure per svolgere i suoi compiti e per muoversi in azienda. Nonostante abbia preso molti appunti, non riesce a ricostruire come fare per chiedere un permesso di un’ora. Smarrita, chiede al collega vicino di scrivania che le dà il numero di telefono delle risorse umane, per sicurezza.
Pietro sta inserendo i dati nel 730 precompilato. A un certo punto ha un dubbio, che prova a risolvere con il manuale messo a disposizione da Agenzia delle Entrate: un PDF di 152 pagine con un indice non navigabile. Per fortuna c’è almeno la casella di ricerca dell’applicazione su cui lo legge: in ogni caso, quando trova una spiegazione che potrebbe fare al caso suo, è troppo complicata e non è sicuro di aver capito come fare. Non vuole rischiare di sbagliare: telefona al CAF e prende un appuntamento per farsi aiutare.
Documentazione, documentazione ovunque!
Abbiamo a che fare quotidianamente con istruzioni e procedure, in contesti più o meno piacevoli o complessi. Quando questo insieme di informazioni assume una forma scritta, parliamo di “documentazione”. Documentarsi significa procurarsi le informazioni, i documenti o simili necessari a conoscere con precisione qualcosa1: la documentazione è l’insieme delle informazioni che ci consente di farlo.
Nel caso di Andrea, la documentazione necessaria per conoscere i dettagli tecnici dell’automobile è il manuale d’uso. Per Pietro è il manuale messo a disposizione dall’Agenzia delle Entrate. Per Teresa sembra non esserci una documentazione, perché le informazioni sono trasmesse solo a voce.
Partiamo dal suo caso, e immaginiamo che l’ufficio delle risorse umane risponda a una telefonata per ogni dipendente che non ricorda come prendere ferie, permessi o malattia. L’inefficienza dovrebbe saltarci agli occhi: viene istintivo dire “appuntiamolo da qualche parte, a beneficio di tutti”. Come lo facciamo?
Mettiamo un bel cartello sulla porta dell’ufficio delle risorse umane. “Per chiedere ferie, permessi o malattia scrivere un’email a poveretta_hr@aziendaccia.com. NON E’ POSSIBILE FARLO PER TELEFONO.”
Inviamo una mail a tutti i dipendenti. Oggetto: “ATTENZIONE: istruzioni per ferie, permessi e malattia”.
Aggiungiamo una pagina alla Intranet aziendale: “Richiesta ferie, permessi o malattia”.
La prima soluzione non risolve niente. Mi imbatterei in questa informazione, infatti, solo se andassi fisicamente davanti alla porta dell’ufficio risorse umane, e potrei non farlo affatto. Se tanto mi dà tanto, poi, questo potrebbe non essere l’unico cartello rumoroso e sgarbato IN MAIUSCOLO, attaccato lì con lo scotch.
La seconda potrebbe essere un compromesso, scegliendo un oggetto migliore: una mail che raccoglie in modo schematico le informazioni essenziali da inviare a ogni nuova persona in azienda, da conservare nella posta elettronica e facile da ritrovare attraverso una ricerca. Good enough, in molte circostanze.
La terza potrebbe essere ideale per aziende che hanno almeno già una forma di gestione delle informazioni strutturata, che comprende anche le pratiche aziendali.
Il contesto, sempre lui
Il contesto in cui leggiamo la documentazione gioca un ruolo fondamentale. Se la documentazione non è pensata per essere usata con efficienza nel momento e nel contesto in cui serve sarà inutile, persino problematica.
«Dimmi un po’, Potter» disse Piton dolcemente, «sai leggere?»
«Sì» rispose Harry, le dita serrate attorno alla bacchetta.
«Leggimi la terza riga delle istruzioni, Potter».
Harry guardò la lavagna strizzando gli occhi; non era facile decifrare le istruzioni nella bruma di vapore multicolore che riempiva il sotterraneo.
«“Aggiungere la pietra di luna in polvere, mescolare tre volte in senso antioriario, lasciar bollire per sette minuti, poi aggiungere due gocce di sciroppo di elleboro”».
Il suo cuore ebbe un tuffo. Non aveva aggiunto lo sciroppo di elleboro, ma era passato alla quarta riga delle istruzioni dopo aver lasciato bollire la sua pozione per sette minuti.
«Hai fatto tutto quello che c’era scritto alla terza riga, Potter?»
«No» rispose Harry molto piano.
«Prego?»
«No» disse Harry più forte. «Ho dimenticato l’elleboro».
«Lo so, Potter, il che vuol dire che questa porcheria è del tutto inutile. Evanesco».
Ora, potrei suonare impopolare, ma spesso chi scrive la documentazione somiglia proprio a Piton2 in Harry Potter e l’Ordine della Fenice, che non ha alcuna intenzione di mettere in dubbio la chiarezza delle sue istruzioni e non perde occasione di dare dello stupido a Harry, che non è riuscito a leggerle. Una lavagna distante in una stanza piena di “bruma multicolore” forse non è la soluzione migliore. E poi, come sarà stata scritta la ricetta?
Così:
Aggiungere la pietra di luna in polvere, mescolare tre volte in senso antioriario, lasciar bollire per sette minuti, poi aggiungere due gocce di sciroppo di elleboro.
O così?
Aggiungere la pietra di luna in polvere
Mescolare 3 volte in senso antioriario
Lasciar bollire per 7 minuti
Aggiungere 2 gocce di sciroppo di elleboro
Scegliere informazioni essenziali, esporle in modo sintetico e strutturato, documentarle nel luogo e sullo strumento più adatto alle esigenze d’uso delle istruzioni stesse, sono punti chiave per una documentazione funzionale. Possiamo capire quali siano le informazioni essenziali, scegliere dove e come documentarle solo conoscendo i destinatari della documentazione.
Gentili inviti a leggere la documentazione, disattesi
Quando penso alla documentazione del software mi viene sempre in mente l’acronimo RTFM, Read the Fucking Manual, annotato persino da Severgnini nel glossario di L’inglese. Lezioni semiserie. L’uso è documentato fin dagli anni Sessanta e Settanta, nelle comunità hacker e ingegneristiche.
L’ingegnere ti dice “tieni, questo è il manuale di duemila pagine per usare il mio software; il software funziona quindi non ti puoi lamentare: questo è il manuale studialo”, no? Questo tipo di approccio oggi non è concepibile.
, Le persone contano, intervista per Radio Ux
Quando la documentazione è enciclopedica, anche il più ardito topo da biblioteca è scoraggiato: chiedere informazioni a qualcuno diventa la soluzione più semplice, e la documentazione fallisce3.
Per una sensibilità più contemporanea, c’è chi consiglia di interrompere l’elitarismo della cultura tecnica verso i non-tecnici, e di usare compassione ed empatia verso le domande che si ricevono. Non sono certo contraria, ma penso che una documentazione ben strutturata aiuti entrambe le parti.
I problemi della documentazione
Gli effetti di una documentazione inefficace sono chiari: proviamo a fare una lista di questioni da risolvere per progettarla meglio. Partiamo dal chiederci:
Chi leggerà la documentazione?
Quali sono le domande e i dubbi a cui ha bisogno di rispondere?
In che circostanze avrà bisogno di consultare la documentazione?
Siamo in ospedale e dobbiamo attivare una quarantena? Non è una cosa che capita tutti i giorni, dovremo attenerci a una procedura scrupolosa: è possibile che abbiamo bisogno di consultare la documentazione. Stiamo usando un nuovo software e non riusciamo a svolgere un compito? Potremmo aver bisogno di consultare la documentazione d’uso, per delle istruzioni passo passo. Non solo il contesto, ma anche gli stati d’animo sono molto diversi.
E ora osserviamo diversi tipi di problemi, per capire come evitarli o risolverli.
Troppo lunga e complessa: scoraggia la lettura. Informazioni sintetiche e mirate sono più efficaci.
Scarsa organizzazione e accessibilità: trovare le informazioni è complicato e faticoso.
Mancanza di aggiornamenti e pertinenza: la documentazione invecchia in fretta, e viene ignorata.
Assenza di esempi pratici o di contestualizzazione: gli esempi su come applicare le informazioni aiutano a percepire l’utilità della documentazione.
Carico cognitivo e formati non intuitivi: PDF non ottimizzati per la lettura rapida, linguaggio complicato o gergale rendono la documentazione inefficace.
Cultura aziendale e mancanza di incentivazione: in molte aziende si privilegia l’apprendimento sul campo alla lettura delle fonti.
Esperienza di lettura: con una formattazione o un layout sgradevoli, anche il miglior contenuto rischia di non essere letto.
Una documentazione ben progettata favorisce la sostenibilità: permette di non sprecare risorse, promuove l’efficienza, minimizza i consumi energetici ed estende la vita dei prodotti. E ci semplifica la vita, casomai ci sembrasse poco.
Vuoi lavorare sulle tue competenze di scrittura?
Esercizi
Dai un’occhiata alla guida How to ask questions the smart way. Come riorganizzeresti il contenuto per migliorarne la chiarezza?
Hai provato a svolgere uno degli esercizi e vuoi parlarmene? Rispondi a questa email o in un commento: sono contenta di discuterne insieme.
Un libro
Douglas Adams, Guida galattica per autostoppisti: la Terra sta per essere demolita per fare spazio a una superstrada intergalattica. Prima che accada, Arthur Dent viene salvato dall'amico Ford Prefect, un alieno camuffato da umano e redattore della “Guida galattica per autostoppisti”, una sorta di enciclopedia intergalattica elettronica, progettata per aiutare i viaggiatori a sopravvivere e orientarsi nel vasto e spesso pericoloso universo. È simile a un piccolo computer portatile, con uno schermo e un’interfaccia semplice per consultare le informazioni: le voci al suo interno sono spesso incomplete, contraddittorie o ironiche.
Devo confessarti che ho letto la Guida molti anni fa e non sono diventata così fan da proseguire con gli altri cinque libri. Ma dato che è un cult, se ancora non l’hai letto potresti dargli una chance.
Qualcosa di utile
Se sei paziente e apprezzi i puzzle o il modellismo, potrebbe piacerti anche questa variante: i “book nook diy”, delle riproduzioni in miniatura in genere di stanze, da infilare sullo scaffale tra un libro e un altro. Io mi sono divertita con la stanza da musica che vedi nell’immagine, di cui ti lascio il link. Non dimenticarti di comprare anche abbondante colla vinilica, se l’idea ti stuzzica.
Tre link
Trasforma la to-do list in una to-learn list: Rethink: Why your to-do list isn’t working (and how to fix it)
The Future Is a City: Megalopolis and Why Architecture Matters to Sci-Fi
In ascolto
Se usi Spotify puoi salvare la playlist.
Potresti voler leggere anche
Note
loZingarelli 2022
Il professor Piton, Letizia.
Esiste anche una variante più generale: STFW sta per Search the Fucking Web, di cui preferisco la versione passivo-aggressiva Google is Your Friend. C’è anche il musical, ti lascio il video. Un’alternativa più sbrigativa è Let Me Google That for You, altrettanto sarcastica.
Renderei questa lettura obbligatoria per tutti coloro che lavorano nell'ufficio compliance. ("Ma perché non leggono la policy che abbiamo scritto?!?!")
Da persona che ha fatto sviluppo software e cresciuto a pane e RTFM, sono ahimé nella minoranza di persone che leggono la documentazione, e nella ulteriore minoranza di persone che documentano tutto.
Sono completamente d'accordo sul fatto che la buona documentazione debba essere un compromesso tra l'essere esaustiva ed essere sintetica: la documentazione deve risolvere un problema a qualcuno e a volte è proprio il non essere in grado di empatizzare con quel o quei "qualcuno" la causa di documentazioni criptiche o enciclopediche.
E se proprio tutto fallisce, come ho sentito dire recentemente, scrivere documentazione come minimo servirà a te che la scrivi, per pensare meglio.