Il primo, vero utente della documentazione…

Documentare le cose richiede generalmente una buona quantità di tempo e di fatica: è incredibile quante parole si riescano e si debbano spendere anche per lavori di taglia modesta. Di più: non è raro che lo sforzo di gestire le scartoffie ecceda quello di produrre le cose a cui si riferiscono.

Il trucco più banale è che la documentazione “viva” parallelamente a ciò a cui si riferisce: un conto è doverla scrivere a lavoro concluso, un conto è farlo pian piano, a lavoro in corso.

Inoltre, per esperienza, fare le cose a lavoro concluso coincide spesso col doverle fare di fretta, all’ultimo momento utile. O, peggio, a distanza di qualche tempo, il che espone il documentante a dover ricostruire mentalmente e poi mettere nero su bianco quello che ha fatto.

A parte tutto questo, abbastanza logico e banale, vorrei sottolineare un paio di cose.

Documentare è dimostrare

Dal momento che, per ragioni pratiche, la documentazione viene generalmente scritta di pari passo con il relativo lavoro, essa appare come dimostrazione chiara ed accessibile del lavoro stesso: nessuna persona seria si sogna di scrivere di aver fatto qualcosa quando in realtà non l’ha compiuta; piuttosto scriverà meno, per omissione deliberata o per dimenticanza, non di più.

Corollario: la documentazione, se scritta in modo comprensibile, è l’equivalente di un “reperto” valido ed intellegibile per la “corte”-committente. Il codice di per sè stesso non è pressoché mai una prova accettabile, almeno fintanto che non lo si manda in esecuzione e si verifica che faccia tutto quello che dovrebbe fare.

Una buona documentazione è una valida autocertificazione del vostro operato.

Istantanea della situazione attuale

Se la documentazione viene scritta ed aggiornata di pari passo col lavoro, essa riflette esplicitamente lo stato di avanzamento lavori.

Nessuno vieta di mantenersi una traccia delle novità introdotte nel tempo (changelog), in modo da poter ricostruire i vari momenti di lavori (e le feauture inserite) anche e soprattutto in un secondo momento. Tuttavia, a differenza di un documento di specifica, non è utile nè elegante accludere l’eventuale changelog direttamente nella documentazione stessa.

Il cliente-medio non ha tempo nè voglia di spulciare in profondità anche quel tipo di informazione-extra – le novità introdotte a partire da una data versione -, per cui quello che deve ottenere deve essere sempre e solo l’ultima versione nota della documentazione, senza indicazioni di revisione o altro. Questo non significa però che, fornendo al committente una nuova e completa edizione della documentazione, non gli si possano anche indicare, magari in un altro piccolo documento (mail?) le singole novità rispetto alla versione precedente (riassumere le modifiche rispetto a più di una versione fa rispetto a quella attuale, diventa improponibile e via via sempre più inutile).

Nuovamente, la documentazione ed il suo eventuale changelog possono servire come prova chiare ed esibibile.

D’altra parte è ben difficile ricostruire la storia di un progetto partendo dal log dei commit di un versioning/revision control come Subversion o Git: nei sistemi come SVN ci finisce di tutto, soprattutto dettagli di basso livello (es: modifiche al codice) che poco hanno a che spartire con la documentazione di più alto livello.

Un conto è la documentazione del codice, un conto è la documentazione del progetto. Non confondete i livelli altrimenti correrete il rischio di porgere una mela a chi vi chiede una pera.

Il primo, vero utente della documentazione

Non ho stime o percentuali da riportare – supposto ne esistano – ma non mi pare proprio che la documentazione goda di grande successo presso il pubblico/utente finale (eufemismo): quante volte avete (abbiamo) comprato qualcosa e avete (abbiamo) deciso di usarlo subito, senza guardare la documentazione? Diciamocelo: il manuale viene letto quando le cose stanno già andando male o quando le cose non sono abbastanza facili ed intuitive da essere usate.

Sarò eretico: così come nella mia testa ogni nuova legge che uno Stato introduce è una sconfitta per la porzione di genere umano che esso amministra, incapace di stare a suo posto senza imposizioni dall’alto, ritengo che costringere l’utente medio a dover leggere un manuale per poter compiere azioni ragionevolmente banali con un prodotto sia uno scorno alla sua intelligenza ed ad una serie di “paroline magiche” come usabilità, accessibilità, eccetera. Detto questo e a prescindere dalla credenza popolare – che tende a fare di tutta l’erba un fascio – non tutto è sempre così intrinsecamente facile da non necessitare di un manuale per essere utilizzato, soprattutto quando c’è in gioco la vita di qualcuno. Continuare a semplificare le cose con la speranza di renderle alla portata di tutti può significare ridurre o limitare certe funzionalità, scontentando un po’ tutti.

Trovandomi recentemente a dover cambiare la batteria ad una bilancia elettronica da cucina da circa 30€, tutto mi sarei aspettato tranne il dover premere un’astrusa combinazione di tasti prima e dopo la sostituzione fisica della batteria per avviare la complicata fase di ricalibratura dello strumento. Fra l’altro una combinazione di tasti degna del peggiore dei videogiochi sulla piazza. A quel punto il manuale utente, che alla fine mi sono rassegnato a consultare, ha certificato, qualora ve ne fosse il dubbio, l’incontestabile imbecillità di chi ha pensato quell’assurda procedura.

Col software è la stessa cosa. Ditemi quante persone conoscete che hanno iniziato ad usare il computer avendo prima letto, almeno in parte, un qualche manuale. Probabilmente risponderete 1 o 2 in tutta la vostra vita e questi individui rientrano nella categoria paranoide al limite del mi-muovo-solo-se-ben-informato-perchè-se-no-lo-rompo per cui non contano ai fini statistici.

Per cui, non potendo comunque evitare di scrivere la documentazione, la domanda che ogni persona si dovrebbe porre è: chi è il suo primo pubblico e quale dovrebbe essere il suo scopo essenziale?

Rispondere è facile: il primo utente e pubblico è lo sviluppatore stesso ed il suo scopo è levarlo d’impiccio dalle emergenze del cliente.

Invece di perdersi in parole e parole per spiegare fin da subito, nei più infimi ed inutili dettagli, ogni singola funzionalità integrata, che nessuno ragionevolmente userà mai, basta spiegare al meglio come risolvere i problemi (troubleshooting) più comuni, come effettuare operazioni particolari o avanzate, come contattare il supporto e/o a chi rivolgersi in caso di necessità. Questi gli aspetti prioritari, poi ovviamente tutti gli altri.

La documentazione prolissa, al pari di quella sintetica e precisa, con tutta probabilità verrà ignorata fino a quando non sarà davvero necessario. Tuttavia, visto il momento più probabile in cui verrà effettivamente utilizzata nonchè la fretta di arrivare ad una piena soluzione, la documentazione asciutta ed accurata farà la differenza. Ed i clienti saranno immediatamente felici, evitando di dovervi ripetutamente infastidire: un effetto collaterale, normalmente molto piacevole, dell’essere contenti di essere riusciti a risolvere un problema da soli.

Date il giusto peso ai contenuti della documentazione in base all’uso più probabile. Non pensiate che la documentazione sia completa perchè descrive un po’ di tutto: concentratevi e date al cliente quello che gli può ragionevolmente servire. Se il cliente è in grado di risolvere i problemi più comuni dei vostri prodotti da solo, in fretta e senza impazzire a dover cercare informazioni in un mastodontico manuale utente, risparmierete “automagicamente” un sacco di tempo e di soldi: la documentazione come kit di automedicazione per il cliente. Fissate quello che la vostra documentazione-modello deve avere e revisionate questo modello nel tempo, rispetto a quello che i vostri clienti richiedono con maggior frequenza. Partendo dal presupposto che, come direbbe Platt “Il tuo utente non sei tu” voi non siete i destinatari finali della documentazione, però siete i primi a poterne beneficiare. Se la documentazione è a posto, potete rapidamente rimandare i clienti ad essa: la documentazione come kit di autodifesa per voi stessi. Come si dice in questi casi: RTFM! (Ecco, magari non proprio con questi termini ma con parole più “tranquille”, ma il senso fra le righe è quello).

Che ne pensate?