A chi non è mai capitato di sentirsi rispondere col tanto vituperato quanto spesso giustificato RTFM? Ehi, cosa sono tutte quelle mani alzate? Razza di Farisei…

Il problema della documentazione del software è piuttosto critico. Ricordo quando ero bambino e mio papà era circondato da questi libroni mastodontici dai titoli altisonanti tipo EPSON DOS, AutoCAD R10, MEGADOC, GW-BASIC [1] e io ne ero oltremodo affascinato perché dentro c’erano le istruzioni per far funzionare i computer, e per me chi le scriveva doveva essere, se non della stessa sostanza, almeno paragonabile a quei tre a cui mia nonna mi faceva rivolgere le preghiere prima di andare a dormire.

La figura dello scrittore tecnico tra la fine degli anni ’70 e la metà degli anni ’90 ha conosciuto un notevole momento di lustro, principalmente perché allora i computer servivano a gente che aveva bisogno di risultati e poco tempo da perdere. Incidentalmente nel 1987 appare sul mercato il Macintosh II e dal 1991 inizia la celebre serie di McGraw-Hill col titolo “DOS For Dummies“. Un caso? Noi di Voyager pensiamo di no.

Da quel momento l’editoria informatica, allora dominata dai manuali tecnici e dai libri Jackson — almeno in Italia — viene invasa dai più disparati testi su qualsiasi software, scritti da chiunque abbia passato col suddetto più di tre ore consecutive. Ma con la metà degli anni ’90 succede anche un altro fenomeno interessante: si diffonde l’Internet commerciale ad un numero sempre più ampio di persone, e le documentazioni iniziano ad essere trasmesse in rete, e sempre più sviluppatori, specialmente quelli gravitanti attorno alla galassia del nascente software libero, iniziano a pubblicare liberamente le documentazioni dei loro software. È l’inizio della fine.

Il vantaggio dello scrittore tecnico è che si trattava principalmente di uno scrittore che aveva acquisito competenze sufficienti a capire i dettagli di un software e a tradurli in una prosa asciutta e chiara, utile a chi, non familiare con un certo prodotto, si trovava a doverlo imparare. Il problema dello scrittore tecnico è che era ben conscio delle sue capacità e della sua importanza, e quindi riteneva — a ragione — di dover essere pagato cifre rispettabili. Purtroppo per lo scrittore tecnico, in un mondo sempre più ampio e in rapida evoluzione come quello dell’informatica nell’ultima decade del secolo scorso, la quantità di materiale che doveva essere prodotta stava diventando enorme, e molte aziende hanno pensato di bene di poter fare a meno di questa figura, anche perché tanto c’era questa ottimistica idea per cui nei seguenti cinque-dieci anni saremmo diventati tutti talmente familiari con i computer che non ci sarebbe stato più bisogno di documentare alcunché. Qualcosa dev’essere andato terribilmente storto perché l’ultima volta che ho controllato alcuni studenti di facoltà umanistiche dei primi di questo secolo avevano difficoltà ad accendere un computer, lascia stare ad usarlo… ma peggio ancora, questa linea di pensiero ha implicitamente legittimato quella goliardia informatica per cui “il codice è abbastanza autoesplicativo” e “ignorare i commenti porta via tempo alla compilazione” che, per carità, sono osservazioni corrette e divertenti per una discussione al bar tra programmatori [2] ma assolutamente deleterie sul lungo periodo.

Quest’idea che documentare il software sia un’attività di importanza marginale ha trovato terreno fertile proprio in quegli ambienti in cui i programmatori lavorano per hobby e quindi hanno poco tempo e non sono pagati, col risultato che pochi progetti hanno una documentazione decente, pochissimi progetti si sforzano di produrre documentazione di qualità, e la maggior parte viene rilasciata “così com’è, nella speranza che sia utile ma senza alcuna garanzia, neppure l’implicita di raggiungere un certo scopo” [3].

Insomma, tutto questo pistolotto per dirvi che la documentazione di CakePHP 2.x fa schifo e che ho ricominciato LitRev usando Ruby on Rails 3 che non solo ha un linguaggio molto migliore di PHP alle spalle, e non solo è il framework che CakePHP vorrebbe imitare ma col linguaggio che si ritrova non è che uno può pretendere, ma anche che ha una documentazione di tutto rispetto: chiara, concisa ed esaustiva.

Un caso? Noi di Voyager… avete capito.

1. Quasi tutti in maiuscolo anche quando in realtà il nome del software in questione non lo richiedeva.[↑]
2. No, aspe… programmatori al bar… c’è qualcosa che non va.[↑]
3. Parafrasando la GPL che è ben diversa dalla FDL ma che comunque cattura l’idea di fondo.[↑]