Unità di apprendimento 5
Documentazione del software
La documentazione del progetto
In questa lezione impareremo...
• la necessità di documentare
• la documentazione esterna di sistema
• la documentazione esterna utente
• i tool di documentazione del codice
Generalità
• Documentare il software è sicuramente una attività non gradita dagli
sviluppatori
• Spesso viene eseguita dagli stessi solo al termine dello sviluppo
unicamente con lo scopo di completare il pacchetto software prima
della consegna al cliente
• È invece importante che venga effettuata contemporaneamente alle
diverse fasi di realizzazione del progetto.
• La stesura della documentazione deve quindi seguire il più possibile le
fasi definite nel processo di sviluppo del sistema
• Deve prevedere la compilazione di un insieme di documenti in
relazione temporale con il completamento delle stesse.
Generalità
• Non esiste uno standard che descrive rigorosamente i documenti che
devono essere prodotti
• Elencheremo gli elaborati cartacei che dovrebbero essere prodotti
durante lo sviluppo di un prodotto software di medie dimensioni,
come indicato dai maggiori teorici dell’ingegneria del software.
• Standard della documentazione
• È importante definire un proprio standard nella produzione della
documentazione da mantenere per tutti i documenti che vengono
prodotti
• Elenchiamo di seguito un insieme di punti che devono essere definiti
dal responsabile del progetto prima dell’inizio del progetto stesso.
Standard della documentazione
Standard per la produzione di un documento:
• per i documenti: descrivono la struttura, il contenuto e l’editing del documento;
• per la presentazione di un documento: definiscono i font, stili, l’uso di un logo
ecc.
Standard per la manutenzione di un documento:
• per l’identificazione di un documento: i documenti sono codificati per essere
univocamente identificati;
• per l’aggiunta di un documento: come i documenti vanno codificati e validati; come
gestire le versioni con il registro delle funzionalità apportate con i vari riferimenti, il
numero e la data;
• per l’aggiornamento di documenti: definire come le modifiche di una precedente
versione si riflettono in un documento, con i vari riferimenti, il numero e la data
• Standard per la distribuzione di un documento:
• standard per lo scambio/condivisione di documenti: come i documenti vanno
memorizzati e scambiati/condivisi tra differenti sistemi di documentazione
Documentazione del progetto
La documentazione del progetto si compone di tre parti:
1. il manuale per l’utente;
2. la documentazione tecnica (che comprende anche il codice sorgente);
3. le prove di collaudo.
• Possiamo classificare la documentazione di un progetto secondo quattro
modalità:
• esterna o interna
• in linea o fuori linea
• globale o locale
• per l’utente o per il programmatore
Documentazione del progetto
• esterna o interna:
• esterna: separata dal programma vero e proprio,
• interna: sotto forma di commenti o help contenuti nel file sorgente;
• in linea o fuori linea:
• in linea: richiamabile su richiesta durante l’esecuzione del programma,
• fuori linea: sotto forma di manuale consultabile separatamente;
• globale o locale:
• globale: riguardante il programma nel suo complesso,
• locale: sotto forma di commenti inseriti nel codice sorgente in punti specifci del programma;
• per l’utente o per il programmatore:
• rivolta all’utente: per chi usa il programma, generalmente organizzata in:
– manuale d’uso,
– manuale di installazione,
– help in linea;
• rivolta il programmatore: è specifica per il personale tecnico per lo sviluppo o per la sua
manutenzione, e comprende
– documentazione inerente il progetto e il management del progetto,
– documentazione del codice
La documentazione esterna
• Dopo l’approvazione del preventivo si avvia la realizzazione di un sistema software e viene nominato un direttore
generale responsabile del progetto (project manager).
• La prima attività del project manager è proprio la stesura dell’elenco dei documenti necessari allo svolgimento del
progetto
• Possiamo individuare due gruppi di documenti:
1. documentazione inerente il management del progetto:
• organigramma
• diario di progetto & verbale
• piano di progetto
• norme di progetto
• offerta
• contratto per lo sviluppo, la fornitura del software e l’assistenza all’avviamento
• piano di gestione della qualità
• relazione finale
2. documentazione del progetto:
• analisi del dominio
• analisi dei requisiti (documento SRS)
• specifica architetturale
• specifica di dettaglio
• piano delle prove
• risultati delle prove
• manuale d’uso
Documentazione inerente il management
del progetto
ORGANIGRAMMA
• È un documento che contiene l’elenco dei membri del gruppo di
progetto con la descrizione dei ruoli assegnati a ciascuno di essi
e viene redatto dal project manager prima dell’inizio delle
attività.
• Ogni ruolo viene descritto indicando le competenze di ciascun
membro del progetto ed è soggetto a modifiche dato che nel
corso dell’evoluzione del progetto l’assegnazione di qualche
ruolo potrebbe essere rivista.
ESEMPIO DI ORGANIGRAMMA
Documentazione inerente il management
del progetto
• DIARIO DI PROGETTO
• Rappresenta il registro ufficiale della documentazione del progetto
• contiene l’elenco di tutti i movimenti relativi all’archivio dei documenti
del progetto e del software che si sta sviluppando.
• Ogni movimento viene registrato indicando:
• la data in cui avviene
• una descrizione comprendente il suo riferimento univoco (codifica) la
versione del documento (o del prodotto)
• il nominativo e il ruolo del consegnatario o del ricevente.
Documentazione inerente il management
del progetto
VERBALE
• Tutte le riunioni del gruppo devono essere verbalizzate
• Ogni riunione viene convocata specificando precedentemente l’ordine del giorno
e comunicandolo a tutte le persone che devono parteciparvi
• Lo svolgimento di una riunione segue tale ordine e il verbale inizia riportando
l’indicazione della data, del luogo.
• Dopo l’indicazione della data, del luogo in cui si è tenuta la riunione e dell’elenco
delle persone presenti, si riporta sinteticamente quando emerso dalla
discussione indicando nominalmente gli interventi in modo da poterli tracciare.
• Al termine della riunione viene redatto un verbale che riporti il nome del
compilatore e che, dopo una rilettura, viene fatto firmare da tutti i presenti
Documentazione inerente il management
del progetto
• PIANO DI PROGETTO
• Il project manager deve compilare e tenere aggiornato il piano del progetto che
contiene le attività pianificate:
1. la definizione degli obiettivi;
2. l’analisi dei rischi:
3. descrizione del modello di processo di sviluppo e delle singole fasi
(milestones);
4. stima dei costi;
5. attività di progetto (Work Breakdown Structure, Diagramma di Gantt);
6. consuntivo attività;
7. strumenti utilizzati.
Documentazione inerente il management
del progetto
• Il piano di progetto si divide in due parti
• pianificazione, che serve per stimare realisticamente le risorse, i costi e
i tempi necessari alla realizzazione del progetto
• consuntivazione, per confrontare e avere un riscontro tangibile tra le attività
effettuate e quelle previste, individuare i punti di discordanza e rendere
possibile la pianificazione delle attività future.
• Il piano di progetto è corredato da un documento che tiene conto, nel corso
del tempo, delle variazioni che sono state apportate, il registro delle
modifiche, indicando la causa, la data e un numero progressivo, che indica la
versione del piano e lo identifica univocamente.
Documentazione inerente il management
del progetto
• NORME DI PROGETTO
• Il project manager ha anche il compito di redarre un documento che
contiene le norme che devono essere rispettate durante le svolgimento del
progetto;
• è generalmente strutturato in due parti.
• 1 Convenzioni generali
• documentazione del progetto
• comunicazione
• organizzazione dello spazio di lavoro
• uso degli strumenti
• 2 Norme di sviluppo
• norme di analisi
• norme di progettazione
• norme di codifica
Documentazione inerente il management
del progetto
• OFFERTA
• L’offerta (o preventivo) è il documento che viene sottoposto al
cliente prima dell’inizio dello sviluppo del sistema e deve essere
firmato dallo stesso per accettazione.
• Viene stilata generalmente dal project manager e da un
commerciale e comprende una breve descrizione del prodotto
offerto, i dettagli economici, l’analisi dei requisiti e i tempi di
consegna con l’indicazione delle eventuali penali.
• CONTRATTO PER LO SVILUPPO, LA FORNITURA DEL
SOFTWARE E L’ASSISTENZA ALL’AVVIAMENTO
• Viene redatto al momento della firma per accettazione dell’offerta
• Riporta anche un insieme di clausole accidentali raccomandate
a) limiti delle responsabilità della software
b) modalità di utilizzo corretto del software prodotto;
c) proprietà dei materiali (software) e degli elaborati;
d) tipo di fornitura del codice (sorgente e/o oggetto);
e) criteri, modalità, obiettivi del collaudo;
f) termini di consegna;
g) eventuali penali;
h) periodo di prova del software a decorrere dalla data di collaudo;
i) tipo di assistenza nel periodo di avviamento
Documentazione inerente il management
del progetto
• PIANO DI GESTIONE DELLA QUALITÀ
• In base alle certificazioni di qualità possedute dalla azienda sviluppatrice
deve essere definito il piano della qualità
• Comprende le politiche e gli obiettivi prefissi, in esso devono essere indicati
gli strumenti e le procedure di controllo indicando tempi, tecniche, metodi,
azioni da intraprendere in caso di non conformità e anomalie.
Documentazione inerente il management
del progetto
• RELAZIONE FINALE
• Alla conclusione dello sviluppo e del collaudo del sistema viene
redatta dal project manager
• Contiene
• la descrizione delle funzionalità implementate
• dell’architettura del software e dell’hardware dove è stato
installato e collaudato il sistema
• le informazioni sui linguaggi di programmazione utilizzati
• sull’ambiente di sviluppo impiegati
• la descrizione delle strutture dei dati realizzate
• dell’interfaccia software per l’utente e delle risorse utilizzate
Documentazione del progetto
• ANALISI DEL DOMINIO
• Contiene
• i dati necessari a conoscere l’ambito di sviluppo del prodotto
• una descrizione della azienda e del progetto da realizzare
• la descrizione dei compiti e delle procedure e una analisi
dettagliata del dominio
• Il glossario (raccolta di termini) delle definizioni
• gli acronimi e le abbreviazioni
• le caratteristiche dei clienti e degli utenti
• la descrizione della concorrenza e dei prodotti software
competitori da loro utilizzati.
Documentazione del progetto
• ANALISI DEI REQUISITI
• Il documento di Specifica dei Requisiti Software (SRS) è un
documento fondamentale nell'ingegneria del software che funge da
ponte di comunicazione tra il cliente (o utente finale) e il team di
sviluppo del software. Esso descrive in dettaglio cosa il sistema
software deve fare e come deve farlo. In pratica, l'SRS definisce i
requisiti del software, che sono le specifiche che il software deve
soddisfare.
Documentazione del progetto
• Il documento di Specifica dei Requisiti Software (SRS)
1. Descrizione generale del sistema: Una panoramica ad alto livello del
sistema e del suo contesto operativo.
2. Requisiti funzionali: Una lista dettagliata delle funzionalità del sistema,
insieme a una descrizione di come tali funzionalità dovrebbero
comportarsi in risposta a determinati input o condizioni.
3. Requisiti non funzionali: questi requisiti includono aspetti come le
prestazioni, la sicurezza, l'usabilità, la scalabilità, la manutenibilità e altri
fattori che influenzano il comportamento del sistema, ma non sono legati
alle specifiche funzionalità.
Documentazione del progetto
• SPECIFICA ARCHITETTURALE
• Viene descritta:
• l’architettura del sistema
• la sua decomposizione in moduli funzionali
• la definizione delle informazioni che vengono scambiate tra di essi
e con l’ambiente esterno
• l’articolazione del programma in sotto programmi con particolare
riguardo all’albero di chiamata.
• Nel caso di programmazione a oggetti vengono descritte le singole
classi, le gerarchie, la modellizzazione dinamica e
comportamentale dei singoli componenti.
• Vengono inoltre descritte le interfacce utente
Documentazione del progetto
• SPECIFICA DI DETTAGLIO
• Nella specifica di dettaglio si riprendono i componenti identificati
nel disegno
• Vengono descritte le loro specifiche funzionalità, l’algoritmo
utilizzato, il significato delle variabili passate come parametri, le
eventuali variabili globali utilizzate, le variabili locali di cui fa uso e
quelle di particolare significatività e i singoli casi d’uso.
• Viene quindi allegato il codice sorgente e il modello logico del
database.
Documentazione del progetto
• PIANO DELLE PROVE
• Definiamo dapprima con batteria di prove una sequenza di singoli casi di
prova correlati che prevede la verifica di una funzionalità del sistema in
corrispondenza di determinati input
• deve essere così documentata:
• classificazione della prova
• istruzioni per il verificatore
• risultati attesi
• istruzioni di ripristino
• Il piano delle prove è un documento che può essere articolato in due sezioni:
1. definizione delle prove di integrazione
2. definizione delle prove di collaudo
• Il collaudo termina con la stesura del documento di accettazione nel quale il
cliente sottoscrive il suo soddisfacimento per il prodotto che gli è stato
consegnato
Documentazione del progetto
• RISULTATI DELLE PROVE
• Per ogni caso/batteria di prove viene prodotto un report da parte del
verificatore che riporta
• la data del test
• il tipo di prova identificato con il riferimento univoco
• i dati di prova utilizzati e l’esito
• commento di eventuali risultati inattesi e situazioni indesiderate ed eventualmente
fornendo le indicazioni per una eventuale ripetizione della prova.
Documentazione del progetto
• MANUALE D’USO (O MANUALE UTENTE)
• La documentazione utente comprende:
• documentazione cartacea:
• manuale d’uso;
• manuale di installazione, se il prodotto viene pacchettizzato e
installato dal cliente;
• documentazione elettronica:
• help online;
• eventuale sito di riferimento.
Documentazione del progetto
• MANUALE D’USO (O MANUALE UTENTE)
• Indipendentemente dal suo formato(cartaceo e/o elettronico) devono
contenere le sezioni :
• introduzione
• istruzioni d’uso
• appendice
Tool di documentazione
• Per aiutare gli sviluppatori a produrre la documentazione del codice sono
presenti tool di documentazione automatica
• Questi analizzano il codice individuando appositi contrassegni (tag)
predisposti dal programmatore
• È però necessario porre molta attenzione per rispettare gli standard previsti
dal generatore automatico
• Nessun programmatore ama scrivere relazioni e documenti
• Avere uno strumento di generazione automatica delle documentazione del
codice lo libera da un compito “noioso” e poco gratificante e gli permette di
utilizzare “meglio” il proprio tempo
• È consigliabile produrre questa documentazione durante lo sviluppo, anche
perché la persona più indicata per descrivere un programma è proprio chi lo
sta scrivendo
Tool di documentazione
• Tool esistenti
• I principali tool appositamente sviluppati per effettuare la
generazione automatica della documentazione sono
Javadoc e Doxygen
• Javadoc è stato sviluppato direttamente dalla Sun Microsystems
durante lo sviluppo di Java
• Doxygen è un sistema multipiattaforma per la generazione di
documentazione tecnica di un qualsiasi prodotto software
• Doxygentool può essere utilizzato con codice sorgente scritto in: C++, C,
Java, Objective C, Python, IDL, PHP, C#.
