Nel settore high-tech la documentazione tecnica viene spesso considerata un accessorio. Ecco come trasformarla in valore concreto per il prodotto.
Trasformare la documentazione tecnica in una risorsa di valore
Dopo oltre vent'anni come technical writer, mi stupisce ancora il divario tra le potenzialità e la realtà della documentazione tecnica.
Negli ultimi anni mi sono chiesto come la documentazione tecnica nel settore high-tech possa portare un valore reale al prodotto, anziché essere una semplice appendice.
Dopo aver sperimentato questo approccio su alcuni prodotti, i risultati mi hanno convinto della bontà della direzione. Da allora cerco continuamente occasioni per metterla ulteriormente alla prova. Ora, dopo sei mesi come technical writer in DoiT, vorrei condividere alcune lezioni apprese e qualche nuova riflessione.
Partiamo dalle basi
I technical writer vengono quasi sempre inseriti in un secondo momento nel team di engineering o di prodotto (a seconda di come l'organizzazione concepisce lo sviluppo del prodotto). In fondo, oggi tutti siamo autori ed editori. Quando si è ancora alla ricerca dei primi early adopter, repository GitHub, post sui blog e discussioni nei forum possono rivelarsi più efficaci, anche in termini di costi, per raggiungere il pubblico target.
È solo quando il prodotto ha superato quella fase iniziale ed è pronto a scalare che qualcuno potrebbe proporre di coinvolgere dei technical writer. Per esperienza, la prima cosa che devono fare è stabilire le regole di base, ovvero le convenzioni.
Può sembrare strano mettere le convenzioni al primo posto in un settore che fa dell'innovazione e della creatività un vanto. Eppure, le convenzioni non sono nemiche né dell'innovazione né della creatività. Seguirle sui percorsi non critici riduce il carico cognitivo e aiuta le persone a concentrarsi sulle attività che contano davvero.
Le convenzioni nella documentazione tecnica si presentano in forme diverse: per esempio, una style guide completa ( Google developer documentation style guide, Microsoft writing style guide) oppure un semplice insieme di regole ( AWS document conventions).
Non serve avere una style guide perfetta prima di mettere mano alla documentazione. Un approccio più efficace è costruirla mentre si prende confidenza con il prodotto. In altre parole, durante l'onboarding.
Ecco i passi da compiere in questa fase:
- Cogliere i fondamentali durante le pulizie iniziali:
- Intestazioni e titoli usano sentence case o title case? Sono in forma gerundio (-ing) o verbo base?
- Le procedure sono scritte come elenchi numerati o in forma narrativa estesa?
- Esiste una regola rigorosa sulla virgola seriale (un ottimo argomento se si vuole accendere un dibattito tra autori)?
- Come vengono descritte le interazioni con la UI? Per esempio, l'utente "clicca", "seleziona" o "sceglie" un pulsante?
- Come vengono catturate e visualizzate le schermate? E i call-out?
- Costruire strada facendo la propria style guide interna:
- Selezionare ciò che funziona dagli standard di settore e adattarlo alle proprie esigenze.
- Considerarla un documento vivo, pronto ad accogliere nuovi usi e terminologia inedita.
Una style guide interna è un tassello fondamentale della documentazione tecnica. Non solo aiuta a far crescere il team di autori, ma offre anche linee guida ad altre persone dell'organizzazione che si trovano a scrivere contenuti tecnici, dalla bozza per i technical writer al post per il blog.
Lungo il percorso possono emergere anche temi di maggior rilievo, per esempio:
- Quanto è colloquiale o personale lo stile complessivo?
- Come vengono utilizzati i video?
- Come vengono gestite le informazioni sensibili?
- Chi sono gli stakeholder o i collaboratori attivi della documentazione tecnica?
Non si stupisca di ciò che scoprirà.
Progettare la documentazione tecnica
I prodotti tecnologici sono complessi. Non solo si basano su tecnologie articolate, ma interagiscono con altri prodotti tecnologici, spesso di organizzazioni diverse.
Come si affronta questa complessità nella scrittura della documentazione tecnica?
Una risposta diffusa inizia con: "Dipende". Tuttavia, abbiamo a disposizione due strumenti potenti: framework e modello concettuale.
Framework
Nella documentazione tecnica, un framework può essere un template o una struttura concettuale che agevola la scrittura di argomenti singoli (cioè argomenti che non sono in relazione con altri).
La maggior parte dei post sui blog e delle singole pagine di documentazione tecnica si concentra su argomenti singoli e può quindi trarre vantaggio da un template o da un framework ben definito.
Deve scrivere una guida all'installazione?
Pensi a una struttura in tre parti: prerequisiti (compresi i requisiti hardware e software), esecuzione (i passaggi effettivi di installazione dell'oggetto in questione) e verifica (controllo della versione, esecuzione di un esempio hello-world e così via).
Sta mettendo insieme istruzioni per interrogare dei dati?
Si assicuri di includere i permessi richiesti, query di esempio e una spiegazione dettagliata di input e output.
Anche in assenza di un template, con un po' di pratica si può sviluppare un framework con relativa facilità. Prima di entrare in DoiT ho scritto un post intitolato How to write (and rewrite). L'approccio proposto riguarda principalmente la costruzione di un framework.
Ecco i punti chiave:
- Usare il Minto Pyramid Principle® per portare alla luce la struttura sottostante di un testo complesso
- Creare gerarchie visive per aiutare il pubblico a orientarsi nella complessità
- Predisporre categorie a supporto del percorso dell'utente
Modello concettuale
La complessità dei prodotti tecnologici nasce in larga misura dalle interazioni: tra componenti dello stesso prodotto o tra prodotti dello stesso panorama business/tecnologico, che devono lavorare insieme per formare una soluzione completa.
Di norma non si espone la complessità intrinseca del prodotto. La sua ricetta segreta può interessare ai concorrenti, ma non necessariamente ai clienti.
Bisogna però prestare grande attenzione alle complessità che possono generare attriti esterni. Sono spesso le vere responsabili delle difficoltà dei clienti e persino del team di supporto interno.
Nel suo celebre libro The Design of Everyday Things, Donald Norman spiega che offrire un buon modello concettuale è il principio più importante per domare la complessità. Sono pienamente d'accordo.
Vediamo più da vicino come sfruttare il modello concettuale nella documentazione tecnica, attraverso due esempi tratti dal DoiT Help Center.
Funzionalità building block
Parlando della funzionalità Attributions, il product marketing manager di DoiT Matan Bordo ama dire che è "una delle funzionalità più sticky di DoiT Cloud Intelligence™, se usata correttamente". Se la conclusione è che non è facile sfruttarla appieno, l'abbiamo capito.
Attributions è una funzionalità di tipo building block. Come molti altri building block, da sola fa poco. Tuttavia, una volta colta la sua essenza, lavorarci diventa persino divertente.
In un recente aggiornamento abbiamo rivisto la documentazione della funzionalità portando gli scenari all'inizio, per aiutare gli utenti a capire di cosa è capace prima di accompagnarli nei dettagli delle configurazioni.
Funzionalità plugin dell'ecosistema
A settembre abbiamo aggiunto un articolo intitolato Visualize with Grafana Cloud (contributo del nostro CTO e co-founder Vadim Solovey). Come forse saprà, Grafana non è una soluzione di DoiT, ma un servizio molto diffuso all'interno del Cloud Native Landscape.
Come nell'esempio della funzionalità building block, nell'introduzione abbiamo illustrato la logica dell'integrazione e in quale aspetto può portare benefici a un'azienda che opera sul cloud.
Sia all'interno del prodotto sia nell'ecosistema, un buon modello concettuale rappresenta le relazioni tra i componenti che interagiscono e aiuta così gli utenti a muoversi nel dominio scelto.
Altri vantaggi? Sulla tecnologia c'è una certezza: gli utenti sono creativi quando si tratta di usarla per risolvere i propri problemi. Con un modello concettuale adeguato, scopriranno nuovi casi d'uso del prodotto; meglio ancora, diventeranno evangelist volontari e contribuiranno a farlo crescere.
È un lavoro di squadra
A che punto siamo, dunque?
Convenzioni e framework si possono affrontare con competenze generiche di technical writing (ed è quindi un buon punto di partenza per nuovi assunti o autori junior), mentre costruire modelli concettuali adeguati ai diversi livelli richiede una conoscenza profonda del prodotto.
DoiT è un'azienda tecnologica che fa della propria competenza cloud e della mentalità customer-centric un motivo d'orgoglio. L'ambiente di apprendimento è eccezionale. Gli argomenti discussi nei canali Slack interni e condivisi sul wiki interno o su StackOverflow sono ricchi di contenuti, e le persone sono pronte a condividere ciò che sanno, ad aiutarsi a vicenda e a collaborare per crescere, sia individualmente sia come gruppo.
All'interno del team multidisciplinare di product management, i technical writer sono interlocutori di pensiero per product manager e designer. La capacità di scrivere con chiarezza si fonda sulla capacità di pensare con chiarezza, e questo è di grande valore quando si tratta di far emergere ipotesi implicite e di modellare le funzionalità di prodotto.
Discutendo degli obiettivi del team di technical writing, abbiamo definito la nostra visione: rendere la documentazione tecnica una risorsa di valore all'interno del portfolio prodotti DoiT. La chiave è il lavoro di squadra. Una documentazione tecnica di qualità non è un compito solitario dei technical writer, ma un'impresa che il team di technical writing di DoiT guida portandola avanti insieme a tutta l'organizzazione.