Documentare il codice prodotto

Guida alla scrittura di una buona documentazione di codice

Perché documentare il codice?


1. Userai il tuo codice tra diversi  mesi


Il codice che avete scritto mesi fa è spesso indistinguibile da quello scritto da qualcun altro. Guarderai un file con un affettuoso senso di ricordo. Poi una subdola sensazione di timore, sapendo che qualcuno meno esperto, meno saggio, lo ha scritto.


Mentre passate attraverso questo atto disinteressato di districare cose che erano ovvie o intelligenti mesi fa, comincerete a empatizzare con i vostri utenti. La documentazione permette di trasferire il perché dietro alle linee di codice. Nello stesso modo in cui i commenti sul codice spiegano il perché, e non il come, la documentazione serve allo stesso scopo.


2. Vuoi che la gente usi il tuo codice


Hai scritto un pezzo di codice e lo hai rilasciato nel mondo. L'hai fatto perché pensi che altri potrebbero trovarlo utile. Tuttavia, le persone hanno bisogno di capire perché il tuo codice potrebbe essere utile per loro, prima di decidere di usarlo. La documentazione dice alle persone che questo progetto è per loro.


Se le persone non sanno perché il vostro progetto esiste, non lo useranno. Se le persone non riescono a capire come installare il vostro codice, non lo useranno. Se le persone non riescono a capire come usare il vostro codice, non lo useranno. Se amate davvero il vostro progetto, documentatelo e lasciate che gli altri lo usino.


Esempio di base


Risorse

---------


* Documentazione online: http://docs.cyberangels.it/


Questo basta come intestazione, con un elenco sotto di essa. Gli URL saranno linkati automaticamente.


README


I tuoi primi passi nella documentazione dovrebbero andare nel tuo README. I servizi di hosting del codice renderanno il tuo README in HTML automaticamente se fornisci l'estensione appropriata. È anche la prima interazione che la maggior parte degli utenti avrà con il tuo progetto. Quindi avere un solido README servirà al tuo progetto.


Cosa scrivere

 Assicuratevi di dare ai vostri utenti tutte le informazioni di cui hanno bisogno. Per prima cosa, devi chiederti per chi stai scrivendo. All'inizio, in genere hai solo bisogno di fare appello a due tipi di pubblico:


  • Utenti
  • Sviluppatori

Gli utenti sono persone che vogliono semplicemente usare il vostro codice, e non si preoccupano di come funziona. Gli sviluppatori sono persone che vogliono contribuire al vostro codice.


Quale problema risolve il vostro progetto

Molte persone arriveranno alla vostra documentazione cercando di capire cosa sia esattamente il vostro progetto. Qualcuno lo menzionerà, o cercheranno su Google una frase a caso. Dovresti spiegare cosa fa il tuo progetto e perché esiste.


Un piccolo esempio di codice

Mostra un esempio eloquente di ciò per cui il tuo progetto verrebbe normalmente usato. 


Come ottenere supporto

Mailing list? Canale IRC? Documentate come ottenere aiuto e interagire con la comunità intorno ad un progetto.