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.

Descrizione

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.

Documentazione utente

La documentazione utente descrive semplicemente come il software è utilizzabile. Tipicamente la documentazione utente descrive in maniera approfondita tutte le caratteristiche del software e aiuta l'utente ad utilizzare tali funzioni.

Una buona documentazione deve arrivare a fornire all'utente assistenza fino alla completa risoluzione dei problemi in maniera coerente e semplice. È molto importante che i documenti non siano fonte di confusione e quindi devono essere costantemente aggiornati. Non è necessario organizzarlo in un determinato ordine, ma è sempre opportuno creare un indice per poter facilmente accedere a ciò che si cerca. Ci sono tre principali modi in cui è possibile organizzare la documentazione:

Tutorial: un approccio tutorial è considerato tra i più utili nel caso di utenti nuovi perché fornisce una guida dettagliata che segue l'utente passo per passo fino al completamento della funzionalità.
Tematico: un approccio tematico con capitoli e sezioni concentrate sulla stessa area di interesse possono rappresentare maggiore interesse per un utente intermedio.
Riferimento: i comandi o le attività sono semplicemente elencate in ordine alfabetico o raggruppate in modo logico, spesso attraverso indici e riferimenti incrociati. Quest'ultimo approccio è di maggiore utilità per gli utenti avanzati che sanno esattamente che tipo di informazioni stanno cercando.

Un problema comune tra gli utenti è che solitamente soltanto uno degli approcci elencati viene utilizzato per produrre documentazione. È una pratica comune limitare la documentazione del software fornendo solo informazioni di riferimento sui comandi o sulle voci del menu.

Documentazione Marketing

Per molte applicazioni è necessario avere anche del materiale promozionale che incoraggi l'utente casuale a voler cercare informazioni sul prodotto. Questo tipo di documentazione ha tre scopi principali:

Creare interesse nell'utilizzatore potenziale e infondere in lui il desiderio di essere coinvolto.
Informare esattamente sulle funzionalità del prodotto così che le attese dell'utilizzatore siano allineate con ciò che il prodotto offre
Spiegare la posizione del prodotto rispetto alle alternative che esistono sul mercato.