Documentazione
Definizione
Documentazione è tutto il materiale che documenta le attività di un progetto (e i loro prodotti). wikibooks.org afferma che, in ingegneria, l'obiettivo primario della documentazione di un prodotto è la replicabilità di tale prodotto: You are not an engineer until others can replicate what you have done [...] without your presence [...] without your words [...] without your physical personality on the planet.
I documenti di un progetto software e del prodotto che si sta sviluppando hanno diversi motivi di esistere:
- per i membri del progetto, sono un mezzo di comunicazione;
- per chi dovrà manutenere il prodotto, servono da repository di informazioni sul sistema;
- per l'amministrazione, forniscono informazioni che aiutano la pianificazione dello sviluppo;
- per gli utenti del prodotto, alcuni documenti sono utili per capire come interfacciarsi con il prodotto.
I principali documenti di progetto sono:
- analisi dei requisiti;
- specifica software (descrizione ad alto livello del sistema);
- specifica tecnica (architettura logica);
- definizione di prodotto (architettura di dettaglio);
- manuale utente.
Specifica software
La specifica software dev'essere una descrizione ad alto livello del sistema tramite rappresentazione gerarchica.
Specifica tecnica
La specifica tecnica (ST) segue l'analisi dei requisiti e descrive l'architettura logica del sistema, mostrando ciò che il sistema deve fare senza però fissarne i dettagli implementativi; difatti, la specifica tecnica descrive l'interfaccia di ogni componente del sistema, attraverso più livelli gerarchici di decomposizione. In particolare, di ogni componente vengono specificati:
- funzione svolta;
- tipo dei dati in ingresso;
- tipo dei dati in uscita;
- risorse necessarie per il suo funzionamento.
Definizione di prodotto
Dall'architettura logica procede l'architettura di dettaglio, descritta dalla definizione di prodotto (DP). Questo documento decompone l'architettura in moduli a grana più fine, finché ogni modulo ha dimensione, coesione, complessità e accoppiamento tali per cui i moduli possano essere sviluppati in parallelo dai programmatori. La DP deve fornire tutti i dettagli necessari alla codifica e alla verifica di ciascun modulo[1]. La DP consente di stimare costi e tempi di realizzazione.
Analisi dei requisiti
Una delle preoccupazioni maggiori nel documentare l'analisi dei requisiti (AR) è il tracciamento dei requisiti. Tracciare un requisito significa motivarne l'esistenza, spiegando qual è l'origine di tale requisito (che magari non era esplicito e quindi è stato dedotto da requisiti più espliciti) e badando a garantire la necessità e la sufficienza di ogni requisito. Per fare tutto questo si può usare una matrice, un grafo o una qualsiasi struttura dati appropriata.
Manuale utente
Il manuale utente (MU) ha la funzione di spiegare all'utente come utilizzare il prodotto. Chi lo redige deve stare attento allo stile: deve preferire frasi brevi, paragrafi focalizzati, uso di liste, stile semplice, terminologia precisa e uso della forma attiva dei verbi. Può essere di diversi tipi, a seconda del grado di esperienza dell'utente (manuale introduttivo, manuale completo...) e in diversi formati (cartaceo, PDF, ipertestuale...).
Tracciamenti
In generale, i principali tracciamenti all'interno di un prodotto sono:
- tra requisiti utente (capitolato) e requisiti software (AR);
- tra requisiti software (AR) e descrizione dei componenti (ST);
- tra test di unità e moduli della progettazione di dettaglio (DP);
- tra test di integrazione e componenti architetturali (ST);
- tra test di sistema e requisiti software (AR);
- tra test di accettazione e requisiti utente (capitolato).