Doc is d.o.c.
Vaticinavo oggi a pranzo sull'importanza della documentazione di un progetto. Insomma non c'è una vera e propria linea di "galleggiamento" sull'approccio all'argomento. C'è chi impone di documentare anche i singoli atomi che passano per il cavo di rete e chi proprio se ne strafrega, anzi ti sgrugna dietro perché è un costo.
E ovviamente è un costo, ci mancherebbe. Però si deve valutare lo stato di vantaggi e svantaggi e chiaramente molto dipende dal progetto, dal suo utilizzo e dall'audience. Penso a esempio alle aziende ISO 9001, se da una parte ne capisco l'indirizzamento, nella sua parte pratica ho sempre avuto l'impressione che tutto fosse una grande supercazzola. Cioè gli standard poi li definisci tu come ti va bene, quindi non c'è un vero e proprio protocollo, e chi si occupa della valutazione non la fa veramente sul merito. Quindi alla fine te la canti e te la suoni da solo, salvo esibire il logo di certificazione come il militare con la medaglia sul petto.
Poi ci sono i progetti Open Source, ma ci metto anche quelli commerciali. E qui è tutto un cinema. A mio avviso è una parte importantissima che spesso viene completamente ignorata e i risultati non sempre rispecchiano la mancanza o la completezza di tale aspetto. Cioè ci sono progetti fortunati con zero documentazione.
Penso ad esempio a Wordpress, documentazione eccelsa forse la migliore che abbia mai visto, di recente il Codex è pure stato rivisto in meglio. Ed è uno dei motivi per cui nel 2005 feci lo switch da Joomla, quest'ultimo aveva una discreta documentazione nella versione 1.0, ma poi quando uscì la 1.2 il wiki era una landa desolata. E nel codice avevano cambiato il "cambiabile" per cui alla fine mi trovai a non capirci un tubo ed abbandonarlo.
Più di recente in un progetto in Tomcat, dovendo fare delle modifiche mi documento nel classico Doc. La cosa assurda fu quando arrivai nel forum perché non riuscivo a trovare una via d'uscita e nei vari botta e risposta c'erano personaggi che sparavano delle API che non erano documentate da nessuna parte. E non sai se quelle specifiche chiamate fossero roba deprecata o roba tipo "early version". Cioè faccio queste modifiche con questi comandi e non so se tra un anno esisteranno ancora o meno.... assurdo.
Avendo fatto documentazione per molti progetti comprendo che questo è un costo non indifferente anche sul lungo termine. Ci vuole uno sproposito di tempo per redarre la documentazione, talvolta è più complicato che fare il progetto stesso. Infatti tutto va pianificato, non è che puoi partire a casaccio e poi ritrovarti a barcamenare con le varie sezioni da mettere assieme. Spesso ho notato che conviene scrivere man mano che il progetto viene sviluppato, meno stressante per chi deve redigere perché stacchi un attimo, in più le informazioni che riporti sono più precise perché fresche di realizzazione.
Non ultimo il mantenimento, dopo lo sforzo economico e umano, se non tieni traccia delle modifiche va tutto in malora in brevissimo tempo; oltre il danno la beffa.