Documentazione Software: una condizione di vantaggio

Uno dei cardini della progettazione di soluzioni digitali in Antreem è la connessione tra le attività di analisi, design e sviluppo.
Si segue il prodotto/servizio dalla sua ideazione fino al rilascio in produzione, attraverso tutte le sue fasi di crescita. Questo modus operandi è possibile però solo seguendo un’operazione delicata che viene spesso minimizzata: predisporre la documentazione. Questo processo, spesso troppo ignorato, è in realtà fondamentale per qualsiasi progetto che coinvolga più di qualche riga di codice.

Stilare una documentazione precisa è un potenziale e duplice vantaggio, sia per chi commissiona il progetto, sia per il team che lavorerà alla sua realizzazione.
Nel primo caso, aiuta il cliente ad avere un’idea chiara, definita e scritta di quali sono gli obiettivi del servizio e di tenere traccia del lavoro svolto fino alla consegna dell’applicativo. Inoltre, la documentazione permette anche una riduzione dei tempi nel caso sia necessario implementare nuove funzionalità, permettendo a tutti i fornitori di avere una visione chiara e immediata del funzionamento dell’applicativo. 

Nel secondo caso invece, la documentazione corre in aiuto anche di chi sviluppa la soluzione, per evitare di incappare in blocchi di codice di cui non si comprende bene il funzionamento, soprattutto quando il team è composto da più persone.
Un altro caso comune sono le situazioni in cui si torna a lavorare su un progetto mesi o anni dopo averlo accantonato: tutto quello che era chiarissimo allora, oggi sarà meno nitido. Infine, quando si mette mano a un progetto nuovo (magari per eseguirne la manutenzione) è sempre molto importante che chi ha lavorato prima di noi abbia lasciato una buona dose di documentazione.

Uno degli errori più comuni che si commette a riguardo, avviene nei casi in cui si lavora a stretto contatto con tutti gli attori coinvolti nel progetto: in queste situazioni risulta più comodo chiedere direttamente (magari a voce) delucidazioni riguardo parti del progetto a cui ci avviciniamo per la prima volta. Questa metodologia, che sicuramente fa risparmiare tempo inizialmente, presenta però diverse falle a lungo termine: alcune di queste sono state particolarmente amplificate dall’aumento di lavoro da remoto causato dal periodo di pandemia; se un determinato progetto non era stato adeguatamente documentato erano necessarie decine di call (spesso anche di gruppo) per ri-ottenere un quadro chiaro del lavoro eseguito, in quanto quello che prima magari era il nostro vicino di scrivania ora si trovava a 100km da noi. Ci si è trovati impreparati a gestire la quantità di allineamenti necessari, sprecando quindi molto di tempo che si sarebbe potuto risparmiare con un po’ di documentazione preventiva.

Si possono compilare molteplici tipi di documentazione relativa allo sviluppo in relazione a un progetto, tra i quali ci sono i seguenti:

• documenti di analisi e funzionali, come l’AFU, vengono preparati e compilati prima dell’inizio di qualsiasi attività di sviluppo e delineano il comportamento di un software, oltre a tenere in considerazione le richieste del cliente. Questo tipo di documento viene sempre redatto da sviluppatori e designer che collaborano insieme in modo da ottenere un risultato realmente implementabile;
• documenti tecnici: ne esistono di vari tipi, da quelli più generici come l’Analisi Tecnica (ATE) che indicano che tipo di tecnologia verrà utilizzata per il progetto e perché, fino a quelli che vengono compilati strada facendo con informazioni utili sempre relative alle tecnologie utilizzate;
• documentazione API: sono documenti abbastanza schematici che definiscono come comunicano il Frontend e il Backend. Anche questi dovrebbero, per quanto possibile, essere pronti prima di iniziare lo sviluppo onde evitare sicuri problemi in corsa;
• commenti nel codice: questi sono la forma più basilare di documentazione che viene ovviamente prodotta durante lo sviluppo. È importante che il codice sia ben commentato in modo che non si debba rimbalzare continuamente tra diversi file di documentazione.

Questi riportati sono perlopiù documenti riguardanti la fase di Deliver del nostro flusso. Per quanto riguarda le fasi di Discover e Design esistono altri tipi di documentazione ad hoc.

Allo stato ottimale delle cose ognuno di questi documenti va compilato e, di volta in volta, va deciso chi si occuperà di revisionarli. Per ogni fase del nostro flusso avere dei documenti precisi e aggiornati permette di procedere in maniera efficace con il lavoro e interconnettere in maniera ottimale la fase di analisi, di design e di sviluppo.
È quindi importante affidarsi a un partner tecnologico che dia la giusta importanza alla stesura di una documentazione esauriente: tassello essenziale e prezioso per realizzare un progetto di qualità, anche a lungo termine.