La giusta prolissità…

Salve gente.

Sarà la mia natura di persona PnP (inteso come Pedantic’n Prolix, non come Plug’n Play ) ma quando si parla di documentazione spesso tendo a preferire la prolissità in luogo dell’estrema sinteticità.

Quando invece si parla di codice, preferisco l’esatto opposto, ossia sinteticità e precisione.

Questa mia dualità di visione credo derivi da un aspetto puramente pragmatico: mi aspetto sempre di leggere codice così compatto e chiaro da poter essere usato rapidamente, agevolmente e senza troppi intoppi.

Al contrario, se proprio devo sforzarmi di aprire quel $INSULTO di manuale, mi aspetto di trovarvi ragionevolmente risposta a tutte le mie domande. O quasi.

Credo sia meglio dire che la “verbosità documentativa“, almeno per come la intendo io, non ha nulla a che fare con pomposità e ripetitività.

Se la documentazione che viene prodotta è destinata ad un utente finale, allora ha senso includere pagine introduttive alla materia trattata, magari con un bel glossario dei termini-base per rendere la trattazione più comprensibile.

Ma non è possibile seguire la stessa strada per la documentazione rivolta ad altri sviluppatori!

Sviluppatori e documentazione

Prima legge dello sviluppatore alle prese con la documentazione:

“Non c’è nulla di più odioso per uno sviluppatore che dover scorrere pagine e pagine ‘blablabla-introduttive’ nella documentazione prima di arrivare al ’succo’, ossia a quello che realmente gli serve.”

La seconda legge è in qualche modo collegata alla precedente:

“Uno sviluppatore tende ad incattivirsi brutalmente se/quando scopre che la documentazione che gli è stata fornita è prolissa nella parte introduttiva/inutile ed assolutamente striminzita e carente in quella con le informazioni davvero importanti.”

La terza legge:

“Mai dare ad uno sviluppatore codice e documentazione non allineati. La documentazione ‘per definizione’ è sempre costantemente aggiornata e a portata di mano; altrimenti è solo roba per antiquari o archeologi (con tutto il rispetto e la stima per essi).”

Infine, la quarta:

“Se uno sviluppatore è costretto a cercare le informazioni di cui necessita nella guida-dell’utente-finale perchè la guida-per-lo-sviluppatore è carente, significa che qualcuno ha davvero sbagliato mestiere. E con tutta probabilità non si tratta dello sviluppatore.”

Credo che il motto del “fai agli altri quello che tu ti aspetteresti da loro” sia la chiave per capire come comportarsi e, se serve, limitarsi.

Prolissità non implica far venire il mal di testa al lettore ma metterlo in condizione di poter disporre di sufficienti informazioni, tali da permettergli di proseguire da solo.

Nel dubbio, meglio abbondare che deficere, evitando però di continuare a riscaldare la stessa minestra, irritando così il lettore.

Se un concetto è importante in tutta la trattazione va messo all’inizio e/o in una sezione a sè stante, per poi referenziarlo dove serve, senza mai ripeterlo nuovamente per esteso.

Nel caso si faccia copia-e-incolla da una risorsa esterna – come ormai spesso capita – è bene comunque citarla esplicitamente in qualche modo.

Se il copia-e-incolla è stato impreciso/incompleto o se si sono succeduti svariati aggiornamenti da quando è stato effettuato (come è naturale che sia), la possibilità di risalire alla fonte originale e completa è un bonus non indifferente: gli sviluppatori tendono ad apprezzare molto chi fa risparmiare loro tempo prezioso.

Inoltre, se si tratta di documentazione digitale, è bene non dimenticarsi di “attivare” gli hyperlink per le citazioni: gli sviluppatori detestano dover digitare gli URI/URL a mano!

Codice e documentazione

Da tempo ho elaborato una specie di euristica/stima indiretta sulla qualità del codice in relazione alla sua documentazione:

“Un codice è tanto più pregevole quanto meno volte costringe uno sviluppatore-medio a far ricorso alla relativa documentazione. Sia essa esterna o interna al codice stesso.”

Può aver senso, per una sorta di principio di località, che il codice contenga solo ciò che spieghi come farlo funzionare rapidamente, lasciando il compito di scendere nei dettagli alla ben più corposa documentazione esterna.

Inoltre la scelta di uno stile visivo chiaro e “luminoso” (no, niente colori-evidenziatore! viva i colori-pastello!) e la presenza di molti esempi e grafici/immagini, rendono la documentazione meno soporifera e decisamente più intellegibile. Per favore, evitate lo stile “documentazione-necrologio“: grazie.

In ogni caso, qualunque scelta venga fatta, è fondamentale che essa sia mantenuta per coerenza in tutto il progetto.

Spero di essere stato chiaro e sufficientemente prolisso.

Ciau! ^^