Scrivere documentazione software: COME e PERCHÈ: in questo articolo ti racconto come e perchè sia maledettamente importante farlo sin da subito!
Prima ancora di chiedersi COME scrivere documentazione software è giusto chiedersi PERCHÈ e non PERCHE’ farlo.
Potrei chiudere l’articolo con le parole che concludono la frase, ma non mi sembra carino, eppure il vero perchè dietro allo scrivere documentazione software è uno solo: evitare bestemmie che volano.
Scrivere documentazione per quanto possa risultare una grande rottura di scatole potrebbe, anzi che dico, è LA soluzione alla tua non-rottura di scatole per il tuo futuro e quello di coloro che verranno dopo di te, ma soprattutto: PER TE STESSO E PER IL TUO STESSO TEMPO!
Perdonami per il caps-lock, ma è necessario: così come è necessario spiegarti chi sono.
Mi chiamo Lorenzo Neri e sono un informatico: questo blog così come l’articolo che stai leggendo nascono dagli errori commessi lungo la mia carriera e dalle soluzioni che ho trovato di fronte a me. Quale miglior modo se non condividerle con te?
Incominciamo.
Scrivere documentazione software: PERCHÈ
Dicevo all’inizio dell’articolo che se ti stai chiedendo perchè scrivere documentazione per il TUO stesso software, beh… La risposta la possiamo riassumere nella seguente immagine:
Se non sapessi chi sia costui, devi rimediare assolutamente.
Comunque, per fartela breve: se non vuoi trovarti a bestemmiare tutto il giorno per i tuoi stessi errori e cose che hai scritto nel tuo software ma che dimenticherai tra 20 secondi, ti sei risposto sin da subito: scrivere la documentazione è un ottimo modo per ricordarsi cosa fa il tuo software e soprattutto qual è la funzione legata ad esso!
Cerchiamo però di elaborare un po’ il tutto: sennò, veramente, Mosconi si reincarna!
Perchè scrivere la documentazione del tuo software? Tempo, errori, focus e futuro!
I quattro punti principali sul perchè scrivere una buona documentazione software, principalmente il tuo stesso software, sono proprio il tempo, gli errori, il focus e il futuro.
Vorrei partire da quello più semplice: il futuro.
Il futuro del tuo software: come te lo immagini?
Una volta che hai scritto la base di ciò che stai realizzando, con buona probabilità si passerà alla parte di mantenimento della codebase o di una sua evoluzione.
Che sia tu stesso a continuare a lavorarci o qualunque altra persona (un collega, un collaboratore, attuocuggino, qualche persona sperduta dell’internet che ha trovato una figata clamorosa il tuo Github) difficilmente il tuo software potrà evolversi, debuggarsi o migliorare in linea di massima.
Capire cosa fa in principio la tua codebase è il modo migliore per capire dove sono necessarie le modifiche da fare: una documentazione pulita e puntuale, fa capire a tutti i potenziali eredi della codebase stessa in che modo e perchè una parte del tuo codice fa qualcosa ma soprattutto… come poterci entrare in contatto.
E ironia della sorte, visto che nella maggior parte dei casi sarai prevalentemente tu a doverci lavorare, immagina riuscire a ricordarti a distanza di 19 mesi per quale motivo hai chiamato una funzione “cacca-puzza-slice” senza uno straccio di documentazione.
Tempo: perchè la documentazione software te ne farà risparmiare un sacco.
La frase di prima non è una domanda e no, non ho sbagliato a scrivere: è un dato di realtà.
Ripartendo dall’esempio citato prima, ricordare cose o cercare di capirle a distanza di parecchio tempo, è un’attività che ci costa parecchio. Passare dal capire e/o ricordare perchè una parte della codebase fa una determinata cosa (e magari pure nel modo sbagliato o inaspettato), ci impedisce di focalizzarci sulla nostra vera attività e ci costringe a un continuo switch di contesto.
Essere multitasking non aiuta mai, specialmente in un contesto simile e su questo vorrei citare un articolo di Efficacemente in quanto spiega magistralmente questo concetto.
Il tempo tuttavia, non viene risparmiato solo da te: no, hai letto bene.
Immagina di dover lavorare alla codebase non più da solo ma con un bel popò di persone e/o colleghi: l’aumento di tempo sprecato non è più lineare come nello “switch-context-time” introdotto prima e citato nell’articolo che ho linkato prima… No, nel caso dei gruppi diventa quadratico.
Questo concetto è espresso in una frase tanto diretta quanto famosa ed estratta dal libro “The Mythical Man-Month”:
“Sappiamo tutti che una donna impiega nove mesi a dar vita ad un bebè, dunque nove donne possono fare lo stesso lavoro in un solo mese!”
Sappiamo entrambi che questo non è vero, ma è necessario per rimarcare il fatto che, quando aumentano le persone in un progetto, il tempo necessario per la sua conclusione aumenta esponenzialmente all’aumentare dei collaboratori: immagina cosa può succedere senza avere la giusta documentazione!
Errori: ti piace DAVVERO ripeterli?
Parlo di errori anche stupidi, soprattutto errori stupidi, ma facciamo un esempio!
Per intenderci, ti sei mai chiesto quanto tempo ti porta via ogni volta ricordarti che devi impostare la porta 8082 sul tuo server in locale altrimenti il servizio REST che stai testando sul tuo computer non funzionerà mai tramite HTTPS e perdi tutte quante le volte mezz’ora perché il tuo stesso servizio ti risponde ogni volta con un bell’errore di timeout e pensi alle peggio cose fatte nella tua codebase?
Pensa quanto tempo ti può far risparmiare scrivere questa semplice frase nella tua documentazione: pensa a quanto ne risparmierai per errori ben più seri.
Focus: vedi tu quale fra le seguenti
L’english humor è necessario dopo un testomuro simile, ti pare?
Come accennavo prima, la documentazione ci permette di reperire tante informazioni in poco tempo: questo ci permette di focalizzarci sui problemi VERI che vogliamo risolvere o meglio ancora: NON risolvere problemi che sono GIÀ stati risolti 😉
Direi che sul PERCHÈ abbiamo già parlato parecchio, eppure c’è un quinto motivo che non ho menzionato prima!
Ricordarti subito dove apporre una pezza
No scherzo: questo l’abbiamo citato prima con il discorso della porta, ma in linea di massima ricordarsi subito dove apporre una pezza è uno dei PERCHÈ più forti legati allo scrivere documentazione.
Ma ora FINALMENTE… Veniamo un pochino al COME scrivere documentazione per il tuo software!
Come scrivere documentazione per il tuo software
Dunque, il primo punto, diciamo quel tassellino utile per fare il tutto è questo:
Ok sì, a parte le battutacce e le tue stesse mani, arriviamo seriamente al punto.
La domanda essenziale che devi fare a te stesso è la seguente: a chi servirà la mia documentazione? In altre parole chi utilizzerà il tuo stesso software? I tuoi colleghi, altri informatici? Delle persone totalmente slegate dalla programmazione? Dei manager? Dei marketers?
Le strade da percorrere sono prevalentemente due: una per la platea non tecnica e un’altra per la platea tecnichese… Cioè scusa: tecnica!
E vorrei partire da quella più difficile: quella non-tecnica.
… Pssst! Se vuoi sapere come scrivere documentazione tecnica per i tecnici saltaci direttamente con un click qui!
Come scrivere documentazione software per i NON addetti ai lavori
C’è una parte facile in questa strada più difficile: se la tua documentazione la deve leggere una platea di persone che con il codice hanno un rapporto tale e quale a quello che avresti con un soprammobile, ti sei letteralmente salvato da un punto importante.
Il punto importante è che non gliene frega assolutamente di sapere come hai strutturato le classi, per quale motivo hai usato Dijkstra anziché A*!
Dunque “Hooray!” per te: non è necessario scrivere pile e pile di commenti e di spiegazioni sulle dipendenze.
E allora perchè è la strada più bastarda?
Perchè devi spiegare come si usa il tuo software nel modo più semplice ed immediato.
Punto uno: PERCHÈ dovrebbero usare il tuo software
La prima cosa che devi scrivere è letteralmente “Il mio software ti risolverà il problema X”: non gli importa come dicevo prima il come. Se questa persona ti ha raggiunto, è perchè è fottutamente interessata a risolvere il problema X e se il tuo software glielo risolve il tuo conto in banca aumenterà di volume.
Tutto molto bello, se non fosse che non basta… Eh già.
Punto due: COME dovrebbero usare il tuo software
Solitamente chi non è avvezzo al mondo software e no, nonostante io stesso sia un millennial, persino i giovini baldi della generazione Z nativi digitali spesso non sanno a cosa serve il tasto “CTRL”, ha bisogno di essere accompagnato a braccetto verso la soluzione.
Immagina di dover seriamente spiegare a tua nonna come funziona il programma che hai realizzato e per quale motivo la aiuterà a compilare la dichiarazione dei redditi in due minuti netti.
“Più facile a dirsi che a farsi” ti sento già da lontano.
La realtà è che basta veramente poco.
Il primo punto è capire i requisiti: su quali sistemi operativi funziona il tuo programma? Serve un hardware in particolare? Serve internet?
Poi, la configurazione: Tua nonna deve mettere dei parametri? Nome utente, password, token, codici identificativi?
Infine, ad ogni funzionalità serve un esempio da cima a fondo: come si fa partire una determinata funzionalità, qual è il risultato che si spera di ottenere e quali sono gli errori più comuni in cui i tuoi utenti possono incappare nel processo stesso?
Ultimo ma più importante di tutti: fatti raggiungere in caso di problemi da disastro nuculare.
I tuoi utenti sono il miglior modo che puoi avere intanto per fargli capire che non sono da soli ma al contrario li supporterai.
Non solo: potrebbero aver scoperto qualche bug che tu stesso non hai trovato!!!
Punto tre: come dare vita a tutto questo?
Un modo ci sarebbe: un po’ come ho fatto io con questo blog.
Un sito web, anche uno economico oppure gratis è un modo tanto utile quanto pratico di poter documentare il tuo software: anche perchè di solito chi non è tecnico, non andrà ad incappare neanche morto su Github, Jira, oppure qualche pagina API di qualche servizio.
E se proprio non vuoi creare un sito web, sfrutta i social.
Questo è il meno, parliamo un pochetto degli esempi e dei passi per spiegare le funzionalità di prima.
Il punto più semplice è quello di usare gli screenshot mostrando un passo per volta le funzionalità del tuo software, accompagnati dalle spiegazioni, ma potresti fare di più!
Per esempio, potresti usare dei grafi o dei diagrammi per dare un significato più diretto delle funzionalità stesse: Draw.io e Lucid.app sono due alleati magnifici e gratis!
E se proprio proprio vuoi dare il peggio meglio di te, forse è il caso di creare qualche video esplicativo: anche qui YouTube, Google Drive e Dropbox sono alleati tanto potenti quanto gratuiti!
Ma ora che abbiamo chiarito come spiegare il tuo software ai non addetti ai lavori, parliamo dei rompicoglio… Degli addetti ai lavori.
Come scrivere documentazione software per gli addetti ai lavori
Eh sì, nonostante scrivere documentazione tecnica per i non addetti ai lavori può essere un calvario, lo è altrettanto per gli addetti ai lavori: ma c’è una nota positiva!
Ed è quella che beh… Ci capiamo più velocemente, eppure certi punti sono simili!
Punto uno: a che cosa serve il tuo software? Habemus README!
Non c’è che dire: i readme sono un modo perfetto per scrivere documentazione software in modo semplice, rapido, efficace e completo per farti capire da chi di software ne capisce 😉
Per capire come scrivere un README a regola d’arte (almeno, secondo me), non posso che invitarti a leggere un mio articolo specifico, ma dopo torna qui: promesso? Puoi scoprire qui come scrivere un README.
Punto due: dipendenze, quali sono?
Una parte importante per rendere facile la vita a chi userà il tuo software è quella di scrivere di quali dipendenze ha bisogno il tuo stesso software. Pacchetti? Librerie? CDN? Metti tutto nero su bianco o chi cercherà di far funzionare il tuo software farà nero te (Pensa a me che sono “Neri”…)!
Non solo: specifica quale versione di queste dipendenze: spesso se non si fa attenzione agli aggiornamenti è probabile che i pacchetti legati alle dipendenze di cui hai fatto uso tu non siano più disponibili o peggio causino conflitti con la tua codebase e dunque rendano complicato usarla… Prestaci attenzione!
Punto tre: installazione
Non dare per scontato di avere davanti a te persone scaltre, anzi.
Noi informatici siamo creature strane: metà uomo, metadata.
Ma soprattutto PIGRI.
Specifica per filo e per segno cosa è necessario per installare il tuo stesso software.
Punto quattro: versionamento, tienilo aggiornato!
Ricordi il discorso precedente sulle versioni delle dipendenze? Ecco, anche il tuo stesso software non è da meno.
È importante spiegare in modo esplicito la versione corrente del tuo software e in particolare a quale stai dando supporto e quale si può considerare stabile.
Per questo, forse può tornarti comodo usare il metodo “Major Minor Patch”: il versioning a tre cifre che secondo me hai già visto ma se caso… Dai una sbirciata qua va!
Punto 5: git e contributi, cerca di essere chiaro e (cir)conciso!
Si può contribuire al tuo software? Se sì, forse è il caso di gestire per bene il tuo repository!
Se posso permettermi, forse è il caso di vederti un attimo il concetto di “git flow” che male non fa 😉
Tolta l’organizzazione è giusto capire se vuoi rendere il tuo software aperto a tutti (o a pochi, insomma: decidi tu se renderlo un club esclusivo oppure no) e dunque accettare fork e supporto dagli altri oppure preferisci renderlo closed source.
Conclusioni sulla documentazione software
Insomma, direi che ne abbiamo viste di cotte e di crude, ma con buona probabilità non ne ho viste abbastanza io!
Devi sapere che tutto quello che ho scritto (e grazie se sei arrivato fino a qui!) deriva dalla mia esperienza e quella dei vari colleghi con cui ho convissuto in questi anni di carriera: chi può saperlo se qualcuno come te ha qualche idea bislacca o pirlacca che può rivelarsi utile ed efficace?
I commenti qui sotto sono fatti apposta per questo: usali 😉
