Come si crea la documentazione del software?

Nuovo lavoro, nuovo progetto - e subito nel vivo del codice. Arrivano i primi requisiti, il sistema funziona già in modo produttivo e il vostro compito è quello di familiarizzare rapidamente. Ma invece di istruzioni chiare, trovate informazioni sparse, commenti obsoleti nel codice e colleghi che non sanno più esattamente come funziona il modulo XY. La documentazione ufficiale? Non è disponibile, oppure è sepolta da qualche parte in un wiki dimenticato da tempo.

Quella che dovrebbe essere un'introduzione strutturata allo sviluppo del software si trasforma in un lavoro da detective. Si cerca, si chiede, si interpreta e si perde tempo. Perché senza una documentazione comprensibile, aggiornata e accessibile, ogni compito, per quanto semplice, diventa una sfida. Eppure potrebbe essere molto più facile.

Questa esperienza esaspera l'approccio spesso adottato nelle aziende quando i nuovi dipendenti arrivano e non sanno come iniziare il loro lavoro. Noi diciamo che non deve essere così! Nello sviluppo di software, questo problema viene solitamente risolto scrivendo i risultati importanti del proprio lavoro per i futuri membri del progetto.

In questo modo, i nuovi arrivati possono essere subito operativi quando arrivano in una nuova azienda o in un nuovo team di progetto. Si parla di documentazione software accurata. Il nostro caso di studio esagerato mostra perché la documentazione software svolge un ruolo così importante nel lavoro quotidiano di uno sviluppatore. Oggi vi mostreremo che cos'è la documentazione software!

Perché la documentazione del software è necessaria?

La documentazione tecnica svolge un ruolo fondamentale in ogni progetto software. Rende il codice più comprensibile, facilita la familiarizzazione dei nuovi membri del team e riduce i costi di manutenzione a lungo termine. Senza una documentazione strutturata, può essere difficile correggere gli errori o implementare nuove funzioni in un secondo momento.

In FIDA abbiamo diverse ragioni per scrivere una documentazione tecnica completa:

• Tracciabilità: gli altri sviluppatori (o voi stessi) devono essere in grado di capire a distanza di mesi o anni come funziona il software.

• Efficienza: un software ben documentato riduce lo sforzo di comunicazione e accelera i processi di sviluppo.

• Manutenibilità: gli errori possono essere corretti più rapidamente e le modifiche possono essere apportate in modo mirato.

• Onboarding di nuovi sviluppatori: i nuovi membri del team possono familiarizzare più rapidamente grazie a una documentazione strutturata.

• Scalabilità: una documentazione chiara facilita l'ulteriore sviluppo del software e l'aggiunta di nuove funzionalità.

Come si vede, investire in una buona documentazione software fa risparmiare tempo, denaro e frustrazione a lungo termine, sia agli sviluppatori che agli utenti.

I progetti software si sviluppano in un lavoro di squadra

I critici potrebbero obiettare che non è compito di uno sviluppatore scrivere i protocolli di passaggio di consegne, in quanto fa perdere inutilmente tempo che non è comunque disponibile in un ambiente di progetto agile e dai ritmi serrati.

Tuttavia, questo tempo presumibilmente perso è compensato dal tempo guadagnato grazie a un onboarding più rapido e meno complicato. Un nuovo sviluppatore di software può familiarizzare più rapidamente con i documenti piuttosto che dover prendere appunti su ogni nuovo argomento.

Anche una documentazione completa dei processi di lavoro non esclude la possibilità che alla fine alcune domande rimangano senza risposta, ma la creazione di un database delle conoscenze fin dall'inizio consente a chi non ha ancora familiarità con il progetto di avere una visione d'insieme in modo rapido ed efficiente.

Certo, la scrittura non è una delle abilità principali di un programmatore. Tuttavia, la capacità di tradurre in parole comprensibili le conoscenze e le competenze tecniche e di creare un manuale d'uso per gli utenti è un bonus che può distinguere una buona applicazione da una eccellente.

Le competenze non tecniche sono necessarie anche per lavorare in modo efficiente e cooperativo in un team. Quasi tutti i progetti software vengono sviluppati in team, per cui uno sviluppatore di software oggi deve essere in grado di lavorare in team, soprattutto se si tratta di un progetto ampio e innovativo! Soprattutto nei team di grandi dimensioni o nei progetti a lungo termine, una documentazione software chiara è fondamentale per la manutenibilità e la scalabilità del codice.

Buono a sapersi: alcune aziende impiegano redattori tecnici per garantire la coerenza e la qualità di tutta la documentazione. Gli scrittori tecnici consentono agli sviluppatori di concentrarsi maggiormente su ciò che sanno fare meglio: scrivere codice. Tuttavia, spesso hanno bisogno di spunti (e commenti sul codice) da parte del vostro team per creare una documentazione comprensibile.

Passaggio di consegne agli sviluppatori

Poiché gli sviluppatori non iniziano a programmare indipendentemente dagli altri membri del team, all'inizio di un progetto c'è quasi sempre un passaggio di consegne agli sviluppatori. Il passaggio di consegne inizia con il briefing del progetto: questo contiene il concetto in base al quale il progetto deve essere progettato e contiene informazioni importanti su come deve essere l'applicazione, quali funzionalità deve avere e quali requisiti tecnici deve soddisfare.

Il briefing del progetto viene spesso definito "requisiti". Di solito non elenca attività o compiti specifici, ma fornisce piuttosto una sorta di indice delle funzioni richieste da un programma software che tutti gli attori coinvolti possono utilizzare come guida.

Tutte queste informazioni vengono trasferite a uno strumento di gestione del progetto prima che inizi il lavoro di sviluppo vero e proprio. Vengono creati dei ticket per ogni parte del progetto, le attività vengono stimate utilizzando gli story point e il flusso di lavoro viene definito utilizzando una lavagna visiva, Kanban o una forma alternativa. In questo modo è facile vedere chi, all'interno del team, sta lavorando su cosa, cosa deve essere fatto dopo e quanto tempo ci vorrà per ogni attività.

Cosa deve esserci nella documentazione del software? I passaggi per un processo di consegna di successo.

Ma cosa succede all'altra estremità del processo, quando la vostra parte del progetto è completata? Come sviluppatore, dovete preparare il vostro lavoro in modo che possa essere passato alla fase successiva, ad esempio ai tester di accettazione dell'utente. Dovete anche assicurarvi che la vostra base di codice sia gestibile e navigabile per i futuri sviluppatori che vi lavoreranno e, ad esempio, aggiungeranno nuove funzioni o apporteranno correzioni.

Nel migliore dei casi, quando passate la vostra applicazione alla persona successiva, dovreste adottare le seguenti misure per prepararla al meglio:

1. Commentare il codice

2. documentare le classi, i componenti e i metodi del codice

3. Creare un manuale per la configurazione del progetto ("Guida introduttiva", "Guida rapida", ...).

Sembra un sacco di lavoro? Può darsi, ma è un passo importante, non solo per i colleghi del team, ma anche per voi come sviluppatore originale, per garantire la tracciabilità e la verificabilità in ogni momento dello sviluppo.

Come creare una documentazione efficace

1. commenti nel codice

Cominciamo con il primo passo: commentare il codice. Molti sviluppatori si chiedono: i commenti nel codice sono davvero necessari? La risposta è: dipende!

Fondamentalmente, un codice ben strutturato dovrebbe parlare da solo. Ciò significa che variabili, funzioni e classi dovrebbero avere nomi significativi che riflettano chiaramente la loro funzione. In questo modo, il codice rimane leggibile e comprensibile senza bisogno di commenti superflui.

Tuttavia, ci sono situazioni in cui i commenti sono indispensabili:

• Quando si è scelta una soluzione complessa o non convenzionale, difficile da capire senza una spiegazione.

• Per documentare le ragioni della scelta di una particolare implementazione.

• Per aggiungere dettagli importanti che non sono direttamente visibili dal codice.

Un commento conciso può quindi aiutare gli altri sviluppatori a comprendere più rapidamente il codice e a svilupparlo in modo efficiente.

Conclusione: scrivete i commenti in modo mirato e consapevole, non come sostituto di un codice pulito, ma come utile aggiunta quando è davvero necessario.

2. documentazione di classi, componenti e metodi

La documentazione tecnica di classi, componenti e metodi svolge un ruolo centrale, in quanto aiuta gli sviluppatori a orientarsi rapidamente nel codice e a prendere decisioni informate. Una documentazione dettagliata assicura che le funzioni e le dipendenze siano chiaramente riconoscibili. Ciò consente ai nuovi sviluppatori di entrare più rapidamente in un progetto e ai membri del team esistenti di lavorare insieme in modo più efficiente.

• Le classi dovrebbero contenere una breve descrizione che ne spieghi la funzione e l'area di applicazione.

• I componenti (soprattutto nei framework front-end come React o Angular) traggono vantaggio dalla documentazione di oggetti di scena, stati e metodi (del ciclo di vita).

• I metodi e le funzioni dovrebbero spiegare i parametri, i valori di ritorno e i dettagli speciali dell'implementazione.

Soprattutto se si ha a che fare con linguaggi orientati agli oggetti come TypeScript, JavaScript (con le classi), Java o C#, è comune abbozzare diagrammi UML, che possono essere utili per l'intera documentazione del software e dovrebbero quindi essere assolutamente inclusi nella documentazione. Infatti, questi diagrammi di struttura descrivono visivamente classi, attributi, metodi ed ereditarietà, fornendo un accesso più chiaro rispetto al codice puro. Ciò rende più facile per i principianti comprendere la struttura e le relazioni tra i componenti o i moduli. Strumenti utili a questo scopo sono PlantUML, Mermaid o Draw.io.

3. creare un manuale d'uso

Una volta scritto e commentato correttamente il codice, si può passare a descrivere la struttura complessiva dello sviluppo. Dovete anche pensare all'utente del software. Questa fase viene solitamente eseguita dopo la programmazione e serve a preparare gli utenti all'uso del nuovo software. Le informazioni più importanti per l'utente comprendono le istruzioni di installazione, che descrivono il processo di installazione con l'aiuto di istruzioni passo-passo e schermate. Inoltre, alla documentazione del software possono essere aggiunti capitoli sulle best practice e suggerimenti per l'ulteriore utilizzo del codice o la sua implementazione in altre applicazioni.

Tuttavia, è il vostro team a decidere cosa inserire nella documentazione. Perché solo il team di progetto sa cosa è importante per il lavoro sul progetto, sia nei team di supporto che con gli utenti, in quanto determina il gruppo target che utilizzerà il prodotto fin dall'inizio.

Esistono già molte soluzioni open source sul mercato per la creazione di un manuale utente, che potete utilizzare per descrivere come gli altri possono iniziare a lavorare al progetto o utilizzare il vostro prodotto software. Strumenti utili per gli sviluppatori che scrivono documentazione software sono Docusaurus, readme.io o MkDocs. Di seguito presentiamo alcuni strumenti utili per la documentazione del software che aiutano gli sviluppatori a documentare i loro progetti in modo efficiente.

I più diffusi strumenti di documentazione software per sviluppatori

1 PlantUML - Creare facilmente diagrammi

PlantUML è un popolare strumento open source per creare diagrammi UML utilizzando una sintassi basata sul testo. È ideale per gli sviluppatori che vogliono integrare i diagrammi direttamente nel loro codice.

2 Mermaid - Diagrammi compatibili con Markdown

Mermaid consente di creare diagrammi con una sintassi simile a quella di Markdown. Viene spesso utilizzato in Confluence, GitHub e altri strumenti per visualizzare processi e strutture.

3 Docusaurus - Documentazione con React

Docusaurus è uno strumento sviluppato da Facebook particolarmente adatto agli sviluppatori che vogliono scrivere documentazione con Markdown e utilizzare un'interfaccia basata su React.

4. draw.io (diagrams.net) - diagrammi drag-and-drop

Draw.io (noto anche come diagrams.net) è uno strumento visivo per la creazione di diagrammi e diagrammi di flusso. Offre un'interfaccia utente intuitiva e può essere integrato con servizi cloud come Google Drive o GitHub.

5. mkDocs - Pagine di documentazione statica veloce

MkDocs è uno strumento semplice ma potente per creare pagine web statiche per la documentazione tecnica. Supporta Markdown ed è facilmente configurabile.

6 Swagger - Automatizzare la documentazione delle API

Swagger (OpenAPI) è uno standard per la documentazione delle API REST. Consente agli sviluppatori di generare e testare la documentazione interattiva delle API.

La scelta del giusto strumento di documentazione dipende dai requisiti del progetto. Mentre PlantUML e Mermaid sono ideali per i diagrammi, Docusaurus e MkDocs offrono soluzioni potenti per la documentazione testuale. Se si vuole creare una documentazione API, si dovrebbe prendere in considerazione Swagger.

Come si documenta correttamente il software?

Una buona documentazione software deve essere chiara, strutturata e comprensibile. Per garantirlo, è importante osservare gli standard pertinenti che definiscono le norme per la documentazione tecnica. Una documentazione efficace spiega il funzionamento del software e illustra chiaramente la relazione tra i vari componenti.

Quando si crea una documentazione tecnica, è utile utilizzare diversi formati: Oltre al testo puro, è opportuno integrare esempi di codice e schermate per illustrare visivamente processi complessi. Soprattutto in produzione, la documentazione deve essere aggiornata regolarmente per riflettere correttamente le modifiche al codice e le nuove funzionalità.

La combinazione di una struttura chiara, elementi visivi e specifiche standardizzate rende la documentazione comprensibile e utile non solo per gli sviluppatori, ma anche per gli altri stakeholder.

Altri consigli utili per una buona documentazione software

1. Utilizzare una struttura standardizzata: utilizzare una gerarchia chiara con capitoli e sottocapitoli, in modo che i lettori possano trovare rapidamente le informazioni pertinenti.

2. Scrivete in modo comprensibile e preciso: evitate termini tecnici inutili o spiegazioni troppo lunghe - la documentazione deve essere facile da leggere.

3. Aggiungere esempi pratici: Gli snippet di codice e i casi d'uso aiutano i lettori a mettere in pratica la teoria.

4. Mantenere la documentazione aggiornata: una documentazione non aggiornata porta a fraintendimenti ed errori. Programmate aggiornamenti regolari.

5. Usare il controllo di versione: se possibile, salvare la documentazione in un sistema di controllo di versione (ad esempio Git) per poter tenere traccia delle modifiche.

6. Integrare la documentazione direttamente nel processo di sviluppo: La generazione automatica di documentazione API o di file README aiuta a integrare la documentazione senza problemi.

7. Raccogliere feedback: lasciare che i membri del team o gli utenti testino la documentazione e migliorarla in base ai loro feedback.

Grazie a questi suggerimenti, è possibile garantire che la documentazione sia non solo completa, ma anche utile e di facile comprensione per tutti i soggetti coinvolti.

Quali tipi di documentazione di sviluppo esistono?

La documentazione informa gli altri sviluppatori su cosa fa ogni elemento del progetto e fornisce loro informazioni sufficienti per utilizzarlo nel progetto. Ad esempio, si può dire che alcuni programmatori avrebbero difficoltà a realizzare i propri progetti senza una documentazione completa e senza gli esempi disponibili nella maggior parte dei repository di GitHub. Sebbene la creazione della documentazione richieda tempo e dedizione, è una parte importante del lavoro di uno sviluppatore ed è essenziale per la realizzazione dei progetti.

D'altra parte, la documentazione può anche essere vista come una sorta di manuale d'uso: un documento progettato per aiutare chi sviluppa il software a comprendere funzioni specifiche e a svolgere compiti specifici. Il manuale d'uso della libreria UI "React", ad esempio, spiega come gli utenti possono incorporare la libreria nel proprio software. Allo stesso modo, un manuale d'uso per una specifica API proprietaria o open-source potrebbe delineare i passaggi per recuperare o aggiornare i dati. La documentazione deve svolgere le tre funzioni seguenti:

• spiegare le funzionalità del prodotto

• contenere i dati essenziali relativi al progetto

• servire da base per discutere gli aspetti tecnici di un progetto

Che tipo di documentazione devo scrivere?

Quando si cerca uno strumento per creare la documentazione del software, non c'è uno strumento giusto o sbagliato. Piuttosto, il vostro team deve decidere cosa deve contenere il documento e quali strumenti utilizzare. Prima di tutto, è necessario discutere il tipo di documentazione che si desidera in primo luogo o se si debba scegliere un ibrido di diversi tipi.

I tipi di documentazione del software

Non esiste un unico strumento che fornisca tutta la documentazione che consenta a un altro sviluppatore o utente di utilizzare un software o di implementarlo in altre applicazioni. Piuttosto, diversi strumenti possono aiutare gli sviluppatori a creare spiegazioni significative e coerenti del loro software.

Molti degli strumenti più recenti offrono anche componenti aggiuntivi basati sull'intelligenza artificiale e, a seconda delle esigenze di documentazione di un team, il loro utilizzo può portare a risultati migliori e più rapidi.

Esistono anche altri fattori di differenziazione nella documentazione tecnica. A seconda del vostro ruolo specifico nel team di sviluppo, alcuni tipi di documentazione sono più importanti di altri.

Come sviluppatore backend, probabilmente non avete bisogno di sapere come creare un pulsante o un elemento di un modulo; uno sviluppatore frontend non ha nemmeno bisogno di documentazione sullo schema del database. Vediamo alcuni dei diversi tipi di documentazione.

Documentazione API

La documentazione delle API è uno dei tipi di documentazione più comuni e necessari per gli sviluppatori, soprattutto a causa della necessità di endpoint API. Non solo è necessaria la documentazione delle API esistenti per utilizzarle nei propri progetti, ma anche per le proprie API quando le si passa agli sviluppatori di frontend, ad esempio.

Senza sapere quali endpoint sono disponibili, che tipo di dati possono essere recuperati e quali informazioni devono essere inviate, un'API sarebbe piuttosto inutile! Gli sviluppatori di frontend, in particolare, hanno bisogno di sapere come sono strutturati i dati con cui lavoreranno, in modo da poterli formattare correttamente sul frontend.

La documentazione delle API viene solitamente creata dagli sviluppatori backend di un team. Questa documentazione è fondamentale per gli sviluppatori che lavorano sul frontend. Può essere sotto forma di documento di testo o di documento HTML creato con JSDoc o Swagger.

Documentazione dell'applicazione

La documentazione dell'applicazione contiene informazioni dettagliate su una base di codice, ad esempio quali classi esistono, qual è il loro scopo, quali metodi hanno, quali parametri accettano e quali dati restituiscono. È qui che si trovano tutte le informazioni più dettagliate sul codice.

Questo tipo di documentazione dell'applicazione è solitamente conservata in un luogo accessibile a tutti coloro che partecipano al processo di sviluppo, ad esempio nel repository GitHub del progetto o in un sito web separato per il progetto. In un'azienda, può anche essere memorizzato su file server interni come Google Drive o Confluence.

Non va confusa con la documentazione per l'utente puro, che si concentra principalmente sull'utente finale. Serve all'utente come manuale d'uso del software, attraverso il quale l'utente impara a usare il software. Allo stesso tempo, ha anche lo scopo di spiegare come funzionano i passaggi importanti all'interno dell'applicazione, ad esempio come accedere, inserire dati o salvare documenti.

Documentazione della libreria

La documentazione del software è essenziale se si vuole creare la propria libreria di componenti per un progetto. Dopo tutto, è necessario un modo per informare rapidamente gli altri sviluppatori su come utilizzare la libreria, su quali metodi esistono, su cosa fanno, su quali parametri richiedono e su quali dati restituiscono.

Il documento spiega come installare la libreria, fornisce un esempio di codice, contiene un elenco di tutte le proprietà che i componenti richiedono (e a cosa servono) e molto altro ancora: in altre parole, tutto ciò di cui si ha bisogno se si vuole utilizzare la libreria in prima persona.

Tuttavia, gli utenti guarderanno comunque al vostro codice se hanno bisogno di aggiungere un nuovo metodo alla libreria, ad esempio. Per questo motivo, è importante scrivere commenti esplicativi nel codice, oltre alla documentazione esterna.

Cosa c'è nella documentazione del software

Altri tipi di documentazione che gli sviluppatori a volte condividono vanno dalle informazioni sull'architettura del database, alle linee guida per la distribuzione e il testing, fino alle best practice per l'utilizzo di componenti HTML e UI in un progetto. Potreste anche imbattervi in documenti meno tecnici come descrizioni di progetti, storie di utenti, flussi di utenti, personas, disegni di schermate e asset. Anche gli appunti delle riunioni possono essere inclusi nella documentazione, se ritenuti importanti!

Se non siete ancora sicuri di come scrivere una buona documentazione tecnica, può essere utile dare un'occhiata più da vicino ad alcune note documentazioni dei principali fornitori di software, perché c'è molto da imparare da loro e possono darvi un aiuto online su come costruire la vostra futura documentazione.

Quando cerchiamo su Internet le librerie più popolari e diamo un'occhiata alla loro documentazione, ci rendiamo conto che ci sono alcune caratteristiche che rendono una buona documentazione tecnica: è chiara e facile da capire per gli sviluppatori. Inoltre, i componenti abituali di un manuale d'uso includono una panoramica delle basi, le istruzioni per la messa in funzione, i componenti utilizzabili e le API. Non è raro trovare nella documentazione del software contributi e articoli di esperti e amministratori IT.

Conclusione

Nonostante la serie di standard e di strumenti per la documentazione del software, non esiste una soluzione unica per la progettazione della documentazione del software e, in ultima analisi, spetta sempre a voi e al vostro team di progetto decidere quanto ampia debba essere la documentazione del software, a cosa volete dare priorità in termini di contenuti e a quanto tempo volete dedicare alla documentazione di alta qualità dei vostri risultati. Alcuni team preferiscono documentare tutto, mentre altri registrano solo le parti più necessarie di un progetto (ad esempio, le API). Dovreste chiarire questa domanda all'inizio del vostro lavoro in un progetto per assicurarvi di agire (e documentare) secondo le aspettative.

Siete alla ricerca di sviluppatori di software che, oltre a programmare, sappiano anche scrivere la documentazione del software e possano offrirvi un valore aggiunto in termini di manutenibilità del codice base? Il nostro team di sviluppatori esperti è al vostro fianco. Contattateci oggi stesso e vedremo come possiamo aiutarvi!