Come documentare un progetto software

Se i file “readme” e le guide allegate possono risultare utili per descrivere le funzionalità e gli scopi di un software agli utenti, quando si tratta di fornire indicazioni utili a chi vuole piuttosto mettere mano al codice sottostante occorre seguire un approccio diverso e maggiormente sfaccettato.

I potenziali collaboratori esterni, i volontari o magari i membri del team incaricato di lavorare ai sorgenti necessitano infatti di linee guida precise, documenti leggibili e indicazioni chiare su dove trovare le informazioni necessarie a svolgere il proprio compito al meglio.

Fondamentale, in un qualsiasi progetto di sviluppo che si rispetti, è l’indicazione di tutte le risorse inerenti lo sviluppo (e la location on-line esatta dove poterle recuperare) come di seguito esemplificato:

• Come trovare task utili per nuovi collaboratori come bug semplici e di “primo pelo”, errori di documentazione e simili.
• Come contattare i responsabili del progetto e gli altri collaboratori, con una lista di tutti i canali disponibili quali chat IRC, caselle di posta elettronica e quant’altro
• Come aprire istanze di bug, problemi e proposte di nuove funzionalità.
• Come contribuire concretamente al codice tramite GitHub o altre piattaforme.
• Come impostare un ambiente di sviluppo pienamente funzionale, magari indicando le personalizzazioni alle soluzioni IDE di base.
• Come segnalare il proprio contributo al codice del progetto, così da rispettare una convenzione unica e uguale per tutti.

Un’altra importante fase nella documentazione per sviluppatori consiste poi nell’impostare delle aspettative precise, indicando ad esempio lo stile a cui il progetto dovrà attenersi e il metodo usato dal team principale per prendere decisioni, il modo per classificare un cambiamento di versione minore o una major release e le responsabilità di aggiornare documenti di riferimento e documentazione per gli utenti quando una funzionalità importante viene modificata.

Via | Orchestrate