Come scrivere un manuale utente ed altra documentazione tecnica?
Lavoro da molti anni ormai nel contesto IT. Questo tuttavia non ha fatto di me una programmatrice (… un po’ web designer sì, più che altro perché mi piace creare cose belle). Se non sono diventata una programmatrice e non mi è stato chiesto di farlo, lo devo al fatto che, sebbene spesso non sia troppo esplicitamente sentita come esigenza, di fatto qualche umanista tra gli ingegneri  può rivelarsi molto utile… Qualcuno che sia in grado di capire e poi di raccontare quanto ha capito a diversi audience.

Ma quali e quanti sono i tipi di documenti tecnici che in una condizione ideale dovrebbero essere prodotti per documentare il software?

Vi dimostrerò che solo per produrre questo tipo documenti varrebbe la pena avere in azienda un technical writer. E qui tralascio il contesto delle gare e degli RFP, di cui parlerò sicuramente in un altro post.

Ognuna delle tipologie che andrò a descrivere qui (per ora in estrema sintesi), ha un suo obiettivo e destinatario specifico.

Qualcuno potrebbe chiedersi se ognuna delle tipologie di seguito descritta sia necessaria. In un contesto ideale sì.

Perché io potenziale cliente, ad esempio, dovrei leggere un white paper, quando ho a disposizione la lista di tutte le caratteristiche di prodotto? Perché troppe informazioni di dettaglio non servono per decidere se adottare una prima basilare implementazione. Perchè l’eccesso di informazioni genera confusione. Quello di cui ho bisogno sono chiare indicazioni sul setup ottimale di partenza, nulla di più.

Manuali di prodotto  molto dettagliati e lunghi, che dicono tutto, rendono davvero complicato trovare una specifica informazione. Se il lettore non è sufficientemente motivato, lascerà perdere in cerca di altro. Si potrebbe forse parlare di selezione naturale, ma in realtà si tratta di una opportunità sprecata.

Allo stesso modo basarsi esclusivamente su documentazione di tipo esemplificativa, come sono i white paper, non è sufficiente per chi desideri andare oltre l’implementazione standard, per rispondere ad esigenze più specifiche e complesse.

Poi ci sono documenti redatti per risolvere problemi, come quelli che collezionano i risultati di chiamate al supporto, di domande nei forum o di richieste delle mailing list. Non se ne coglie l’immediata utilità? Un problema viene tracciato e risolto a beneficio di tutti. Risolto una unica volta. Per tutte.

Forse l’investimento in documentazione è costoso, ma è una spesa che ha il suo ritorno evidente e misurabile. Una spesa che si ripaga con i risultati. E una soluzione ben documentata ha più probabilità di essere scelta di una che non lo è, costituendo un reale vantaggio competitivo.

Provo a descrivervi le caratteristiche dei documenti da produrre.

Manuali utente

Che in alcuni casi incontriamo come “Quick start guide”, “how to”, “Tutorial”, guide “step-by-step” e in generale tutti quei documenti che hanno l’obiettivo di descrivere le azioni che l’utente deve compiere per ottenere un ben preciso fine, utilizzando il software documentato. Tutte le azioni da compiere, dall’inizio alla fine.

Questi documenti sono spesso dedicati a nuovi utenti, ma possono interessare anche tecnici dedicati alla configurazione, al deployment e al supporto, o anche a chi si occuperà di predisporre demo e agli ingegneri di prevendita.

Alcuni consigli in merito

  • Utilizzare un linguaggio semplice e comprensibile a tutti
  • Gli utenti destinatari delle guide non devono necessitare di nessun tipo di conoscenza pregressa in materia informatica per seguire il manuale e compiere le azioni descritte
  • Definire chiaramente il punto iniziale del percorso e la configurazione iniziale di sistema. Ad esempio quali altri software è necessario installare, quali versioni.
  • … Se poi il percorso per raggiungere quella configurazione iniziale non è così scontato, è bene descrivere anche quello
  • Non tralasciare o dimenticare alcun passaggio
  • Mi è successo da poco: il manuale è stato completato prima che lo sviluppo avesse definito del tutto la release, sono state cambiate delle cose che non erano state riportate nel manuale pubblicato. Se non vogliamo incorrere in una valanga di ticket al supporto è bene porre rimedio di corsa!
  • Non infilare la descrizione delle caratteristiche del prodotto nel bel mezzo di una descrizione degli step da compiere per utilizzarlo. Meglio un rimando di qualche tipo. Distrarre l’utente dal procedimento è un errore da evitare.
  • Non cercare di fornire nel medesimo contesto anche la documentazione di “Troublesguting”. Di fatto è sempre sbagliato interferire con il percorso dell’utente
  • Descrivere tutte le funzionalità. Non solo quelle più comunemente utilizzate.
  • Sfruttare le informazioni che possono sopraggiungere dopo l’utilizzo del software per integrarle nei manuali, ad esempio la conoscenza di chi ha risolto problemi tecnici durante i tentativi di configurazione.

Documentazione delle caratteristiche di prodotto

Questo tipo di documentazione descrive ogni caratteristica e configurazione possibile. A cosa servono, quando e perché utilizzarle.
I destinatari sono quegli utenti che necessitano di utilizzare il prodotto in modo meno standard e più personalizzato. Potrebbe trattarsi di clienti, ma anche di architetti, del team di supporto o di quello di consulenza professionale.

Un esempio tipico di questo tipo di documenti sono le “Reference guide”.

Alcuni consigli in merito

  • Non inserire queste informazioni nei manuali dedicati agli utilizzatori “standard”
  • Descrivere quando e perché ogni caratteristica dovrebbe essere utilizzata

Documentazione di Troubleshooting

Questa documentazione descrive gli step per diagnosticare i problemi. Include informazioni sui file di log. Include informazioni sui processi e sulle code di lavorazione, i file e le interazione di dati, i processi di background. Questo è uno di quei tipi di documentazione per cui tocca mettere sotto torchio qualche ingegnere insomma 🙂 .

Se gli utenti cercando di portare a termine un task e il procedimento non va a buon fine abbiamo ottenuto un errore su quel singolo task… Tuttavia per sistemare le cose è necessario sapere che, dietro le quinte, hanno concorso dei precisi processi di background, che andranno tutti indagati per risolvere il problema.

Non è necessario che questa documentazione sia pubblica (o almeno si può valutare se renderla tale), ma di sicuro deve essere nelle mani del team di supporto.

Alcuni consigli in merito

  • Non confondere questo tipo di documentazione con quella di “Knowledge Base” (che descrive problemi, cause e soluzioni)
  • Fornire gli step completi per portare avanti la diagnosi, comprensivi di quelli che riguardano convergenze di terze parti. Chiaramente non è necessario riscrivere la documentazione delle terze parti se questa esiste, in tal caso basta un link.
  • Questa documentazione dovrebbe permettere la diagnosi in modo tale da definire molto precisamente il problema: la soluzione in tal caso risulta univoca e inequivocabile.

Documentazione di Knowledge-base

Questa documentazione è comunemente il risultato dei ticket inviati al team di supporto. Quindi viene dichiarato un problema specifico, una specifica causa e una singola soluzione. Questo consente di indagare un problema una sola volta, per poi riproporre la soluzione quando questo problema si ripresenta, accelerando di gran lunga i tempi di risposta del supporto.

Questo tipo di documentazione è dedicata di solito ai team di supporto ai quali sono riportati i problemi, e talvolta ai clienti stessi, se abilitati a gestire da soli le problematiche.

Questo tipo di documentazione è spesso rilasciata sotto forma di Frequently Asked Questions (FAQ).

Alcuni consigli in merito

  • Riportare un solo problema per “paragrafo”.
  • Evitare di fornire una lista di soluzioni, senza dare modo di determinare quale sia quella corretta
  • Fornire una adeguata modalità di ricerca delle soluzioni

Codice, API o documentazione SDK

Questa documentazione descrive come altri possono utilizzare il codice per scrivere add-on e plugin.

Alcuni consigli in merito

  • Aggiornare sempre la documentazione quando si aggiorna il codice
  • Avvertire sempre gli utenti se un determinato codice è stato da voi deprecato

Documentazione interna di sviluppo

Questo tipo di documentazione, ad uso interno, serve agli sviluppatori per lavorare su una parte di codice non precedentemente scritto da loro, e fornisce al contempo indicazioni sull’architettura, usufruendo anche degli standard di modellazione UML.

Ingegnereeee!!! Qui serve, ma un technical writer renderà tutto più bello… Anzi grazie a voi il prossimo sviluppatore ci capirà veramente qualcosa 😉

Casi reali di implementazione da parte dei clienti

Le “customers success stories”, chi non le ama? Però attenzione a non descrivere i casi sbagliati, vale a dire quelli di clienti non propriamente felici del risultato ottenuto… o vi si ritorcerà contro.

Documentazione di marketing

Documentazione che non dice nulla più del necessario, con il solo obiettivo di far conoscere la disponibilità del prodotto ai potenziali clienti.

Alcuni consigli in merito

Attenzione a non renderla troppo complessa, includendo ad esempio immagini difficili da comprendere ai più. Inutile dire che se non avete abilità grafiche equiparabili a quelli di un grafico, meglio chiamarne uno.

Sia chiaro che in alcuni casi sopra descritti è necessario avvalersi del contributo di sviluppatori coinvolti nel progetto, ma la mano di un technical writer di professione per riassemblare, organizzare, rendere leggibile e omogeneo qualsiasi contributo si nota, e spesso è assolutamente necessario…

Se mancasse qualcosa in questa lista sono tutta orecchie…