Documentazione del software

La documentazione software, in informatica ed in particolare nell'ambito dello sviluppo software, è un testo scritto che accompagna un software, con lo scopo di spiegare quali funzionalità assolve il software, come è strutturato e implementato e come lo si utilizza.

Tipologia

La documentazione software ricopre, a vari livelli, un ruolo molto importante nel processo di sviluppo di un software. Tra le tipologie di documentazione ricordiamo le seguenti:

Requisiti: si tratta di dichiarazioni di attributi, capacità, caratteristiche e qualità del sistema.

Architettura e Design: questa parte offre una panoramica del software introducendo le relazioni tra l'ambiente e i principi di sviluppo utilizzati nel design dei componenti.

Documentazione tecnica: include la descrizione del codice utilizzato per implementare il progetto, gli algoritmi e le API.

Utente finale: contiene le spiegazioni dello staff e il manuale di utilizzo.

Marketing: comprende le indicazioni su come pubblicizzare il prodotto e l'analisi della domanda sul mercato.

Documentazione dei requisiti

La documentazione dei requisiti è la descrizione di ciò che il software deve o dovrà fare ovvero le specifiche funzionali. I requisiti sono prodotti e utilizzati da tutti i soggetti coinvolti nella produzione di software: gli utenti finali, i clienti, i product manager, il reparto vendite e marketing, gli architetti, gli ingegneri del software, gli interaction designers, gli sviluppatori o i tester. Per questa ragione la documentazione dei requisiti ha molti scopi diversi.

I requisiti sono disponibili in una varietà di stili, notazioni e formalità. I requisiti possono essere orientati all'obiettivo (es. ambiente di lavoro distribuito) o orientati al design (es. la funzione build può essere avviata facendo clic destro e selezionando la funzione 'build'). Possono essere specificati come istruzioni in linguaggio non tecnico, come figure disegnate, come formule matematiche dettagliate oppure come una combinazione di tutti.

I requisiti possono essere impliciti e difficili da scoprire. Non è sempre facile sapere esattamente quanti e che tipi di documentazione sono necessari e quanti invece possono essere lasciati alla parte di documentazione di architettura e design, è inoltre difficile sapere come documentare i requisiti considerando la varietà delle persone che devono leggerla e utilizzarla. Per questa ragione la documentazione dei requisiti è spesso incompleta o inesistente e senza l'adeguata documentazione le modifiche software diventano più inclini all'errore. La necessità di documentazione varia in base allo scopo del progetto: nel caso di progetti piccoli per sviluppare applicazioni di durata ridotta (per esempio per una campagna) la quantità di documentazione è molto più ridotta rispetto a progetti che riguardano questioni di sicurezza (per esempio nel caso in cui si progetta lo software di un sistema di energia nucleare).

Documentazione di Architettura e Design

La documentazione di architettura è un particolare tipo di documento di progettazione. Nella documentazione di architettura ci sono poche specifiche collegate però direttamente al codice: questa non descrive come si deve programmare un determinato modulo, ma deve spiegare perché il modulo esiste cioè sostanzialmente come è strutturato il software.

Una parte molto importante della documentazione di design nello sviluppo di un progetto software è il Database Design Document (DDD). Questo contiene elementi concettuali, logici e fisici di design e include anche informazioni formali che le persone che interagiscono con il database utilizzano. Lo scopo della creazione del documento è la preparazione di una risorsa comune utilizzabile da tutti gli attori che partecipano al progetto.

Gli utilizzatori potenziali sono:

Database Designer;

Database Developer;

Database Administrator;

Application Designer;

Application Developer.

Parlando del Database Relazionale il documento dovrebbe contenere le seguenti parti:

Schema Entità-Relazione;

Definizione delle entità e degli attributi;

Relazioni e i loro attributi;

Chiavi candidate;

Attributi e Tuple;

Schema relazionale;

Tabelle, attributi, e proprietà;

Viste;

Chiavi primarie e chiavi esterne;

Cardinalità.

Documentazione tecnica

La documentazione tecnica è tutto ciò che la maggior parte dei programmatori intende quando utilizza il termine documentazione software. Durante la creazione di software, il codice sorgente da solo è insufficiente. Ci deve essere del testo allegato per descrivere i vari aspetti del suo funzionamento. È importante mantenere la documentazione tecnica approfondita, ma non troppo dettagliata per poterla aggiornare facilmente. Tale documentazione può essere utilizzata dagli sviluppatori, tester e anche i clienti finali o clienti che adoperano il software.

Spesso, strumenti come Doxygen, NDoc, javadoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText o Report Universal possono essere impiegati per generare automaticamente la documentazione del codice. Ciò avviene con l'estrazione dei commenti che si trovano nel codice sorgente creando poi documenti di riferimento in formato file di testo. L'idea di auto-generazione di documentazione è allettante per i programmatori per vari motivi. Ad esempio, perché è estratto dal codice sorgente attraverso i commenti che il programmatore scrive facendo riferimento al codice. Questo rende molto più facile conservare la documentazione aggiornata.