Sei sulla pagina 1di 29

Documentazione del progetto

Gestione Progetto e Organizzazione dImpresa

Indice

Tipi di documentazione
Enti per gli standard di documentazione
Modello E-M-R
Forme della documentazione
Revisione e versionamento
Redazione di un manuale utente
Codifica dei documenti e tracciabilit
Generazione automatica dei documenti

Tipi di documentazione

Tipi di documentazione

Documentazione amministrativa: linsieme dei


documenti che servono a definire i vari aspetti pratici della
gestione del progetto informatico: contratti, capitolati, preventivi,
offerte, fatture. Sono determinati dalle leggi vigenti e si basa su
modelli aziendali. Tipi di documenti sono:
Fatture, ricevute dacquisto
Richieste di acquisto, preventivi, ordini, conferme dordine
Verbali di consegna e ricevute di pagamento

Documentazione di processo: linsieme dei documenti


che definiscono come devono essere svolte le attivit di un
progetto. Fa parte della documentazione complessiva del
progetto. Pu essere condivisa da pi progetti che utilizzano
quei processi. Possono essere presenti delle modifiche: revisioni.
Devono essere memorizzate per tenere traccia di quali sono le
documentazioni di processo che hanno avuto seguito e quali no.

Tipi di documentazione

Documentazione tecnica del progetto: linsieme dei documenti tecnici

che servono a descrivere la soluzione tecnica sotto diversi punti di vista:

analisi e specifica dei requisiti


progetto architetturale
progetto di dettaglio
documentazione dei testing, della verifica e della conformit dei prodotti software
schemi di installazione e di interazione tra diversi sistemi informatici.

specifica della realizzazione a cui si riferisce. uno strumento di


comunicazione tra gli stakeholder del progetto. I modelli di documento
(template) sono regolati dalle norme ed hanno generalmente un indice
ordinato degli argomenti da trattare.
Esempi di normative:
IEEE 830: spiegano come devono essere redatti i documenti di analisi e
specifica dei requisiti
IEEE 829: spiegano come devono essere redatti i documenti sula verifica
del software
IEEE in generale definiscono le linee guida per la redazione di documenti
nello specifico argomento

Tipi di documentazione

Documentazione del codice sorgente: il


centro del progetto informatico, serve al
compilatore per produrre codice macchina ed
integrato opportunamente pu dare informazioni:

Documentazione delle scelte implementative: quando il


programmatore prende decisioni basate su un
ragionamento non banale. Rilettura pi semplice.
Documentazione dellinterfaccia di programmazione
(API, Application Programming Interface): molti linguaggi
permettono al programmatore di documentare la
struttura del programma. Aiuta i futuri miglioramenti.
Test Unitari: utili sia per testare il programma, sia per
dare allutente un esempio di utilizzo del software

Tipi di documentazione

Documentazione per lutente:


Installazione
Configurazione
Utilizzo
Risoluzione dei problemi: panoramica dei
problemi pi frequenti e relativa soluzione,
FAQ, help online o cartaceo
Diritti dautore: informazioni legali, licenza e
garanzia

Contatti: assistenza tecnica e supporto

Enti per gli standard di documentazione

Nel settore delle tecnologie informatiche

Enti per gli standard di documentazione

Governo: tramite le normative civilistiche, fiscali e/o


la legislazione nazionale e locale
ISO: International Organization for Standardization

IEC: International Electrotechnical Commission

ISO/IEC 12207: per la gestione delCiclo di vita del


software

IEEE: Institute of Electrical and Electronics Engineers

Requisiti
Specificazioni
Linee guida per gli standard

IEEE 802: standardper lereti locali(LAN) e per lereti


metropolitane(MAN)
IEEE 830: analisi e specifica dei requisiti
IEEE 829: verifica del software

OMG: Object Management Group

Linguaggio UML (Unified Modeling Language)

Modello E-M-R
Per un buona comunicazione

10

Modello E-M-R

11

Forme della documentazione


Quale scegliere?

12

Forme della documentazione

Documentazione
cartacea

Documentazione in formato elettronico

13

Pdf
Web
Help proprietari

Revisione e versionamento
Per capire come ci sono arrivato

14

Revisione e versionamento
Revisione:
congelamento di un
documento o di un
oggetto a cui sono state
apportate modifiche di
lieve entit tali da non
stravolgere
limpostazione di base
del documento.

15

Modifica di alcune parti


Inserimento di parti
secondarie
Correzione di errori

Versione: si intende il congelamento di un


documento odi un oggetto a cui sono state
apportate modifiche sostanziali

Riorganizzazione del
documento
Modifica delle finalit
delloggetto a cui fa
riferimento
Inserimento di parti
significative

Revisione e versionamento

Processo di approvazione: sequenza di azioni


di verifica da parte delle figure coinvolte
Nuovo:
[Autore]

bozza

Rigetta con note: [Capo progetto,


Revisore]

Obsoleto

16

Scarta:
[Revisore]

Richiedi approvazione:
[Autore]
in
approvazione
Approva: [Capo progetto]
Approvato
Rappresentazione standard
UML
Diagramma di stato

Revisione e versionamento

Si usa un ciclo approvativo (approval


workflow): interno, normato e noto, si usa un
diagramma degli stati
bozza

Richiedi approvazione: [Autore]

Rigetta con note: [Capo progetto,


Revisore]

Il ciclo approvativo deve essere:


Documentato
Archiviato
Reso accessibile a tutti i
soggetti coinvolti
17

in
approvazione

approvato

Possibili allegati
prodotti da altre
organizzazioni
faranno parte
della raccolta (o
libreria). Non sono
soggetti
allapproval
workflow.

Revisione e versionamento
Il servizio aziendale di archiviazione (ECM:
Enterprice Content Management System cio
Sistema di Gestione dei Contenuti Aziendali) dei
deve:
documenti
Consentire la pubblicazione,
la

consultazione e la conservazione dei


documenti e degli allegati
Consentire la ricerca a tutto testo nei
documenti e negli allegati
Riconoscere gli utenti che accedono al
servizio ed applicare il corretto profilo
operativo
Conservare le versioni di tutti i documenti
approvati e consentirne laccesso
Consentire lapplicazione di un workflow
approvativo
18

Revisione e versionamento
Ci sono vari prodotti per la gestione documentale, sia
commerciali che open-source.
Subversion (SVN) un repository per la gestione del
codice sorgente. (sito: http://tortoisesvn.net/)
Usato

per la conservazione delle revisioni di documenti


informatici di vario genere
Open source di Apache
Strumento client/server
Server:

si possono configurare vari repository (cartelle sul disco


server in cui sono memorizzate tutte le versioni dei file da gestire)
Client SVN: per comunicare con il server di vari generi in base al
sistema operativo (sia open source sia commerciali)

SVN TortoiseSVN con licenza duso GPL (cio uso in forma


gratuita ed installabile su Windows)
19

Revisione e versionamento
Wiki

un sistema di pubblicazione di
informazioni in formato ipertestuale HTML

un normale sito Web in cui la costruzione delle


pagine di contenuti affidata agli utilizzatori
(esempio Wikipedia)
La tecnologia utilizzata quella di Media Wiki
(open source)scritto in PHP
sito: https://www.mediawiki.org/wiki/MediaWiki/it
Consente di
Pubblicare

e consultare le informazioni
Ricercare a tutto testo
Richiedere lidentificazione degli utenti
Consentire lapplicazione di un workflow approvativo
20

Redazione di un manuale utente


User experience

21

Redazione di un manuale utente

Attivit di elaborazione testi che documenti lutilizzo


di un programma da parte di tutte le tipologie di
utente
User experience: rappresentare lesperienza che si
ha durante luso del programma
Esempio HelpNDoc e Wiki
Aspetti organizzativi

22

Il software deve essere completo e funzionante


In varie lingue
Attenzione alle modifiche: il manuale diventa obsoleto
Manutenzione del manuale (tracciabilit)
Stesso versionamento del software e del manuale
Sconsigliata la stesura da parte del programmatore (punto di
vista differente rispetto allutente)

Redazione di un manuale utente

Contenuti:

23

Manuale cartaceo: tipicamente lettura


sequenziale
Sito WEB o manuale HTML: tipicamente lettura
personalizzata
Tavola dei contenuti: suddivisione degli
argomenti per tema
Indice analitico: cio in ordine alfabetico
Avvio rapido: mini guida veloce
Video guida: sito in streaming o file multimediale
Tutorial: spiega particolari aspetti in formato
multimediale

Redazione di un manuale utente


Strumenti

Elaborazione testi (Word processing) e poi stampati


in pdf
Elaborazioni ipertestuali e multimediali: sito web
diviso in varie pagine
Sistemi di gestione dei contenuti (CMS, Content
Management System): sono applicazioni Web che
permettono di creare contenuti multimediali che
hanno laspetto di un sito Web
Sistemi autore: per redigere documentazione
multimediale
Strumenti per la cattura dello schermo (screenshot)
Strumenti per le presentazioni
Registratori di sessione utente: per catturare la
sequenza delle operazioni da fare. Per creare tutorial e
video guida.
24

Codifica dei documenti


Tracciabilit
Dimmi il tuo nome e ti dir chi sei

25

Codifica dei documenti

la sua carta didentit, indica univocamente:

Il contesto produttivo
La storia e levoluzione tecnica del prodotto

Si pu dare un codice di tipo

Numerico assoluto
Parlante, cio composto da pi parti che indicano
alcune caratteristiche del documento:

versione e/o revisione seguono delle numerazioni progressive


a vari livelli

26

1, 2, 3,
a,b,c
I,II,III,IV,

Si possono controllare i documenti che possono stare in diversi


stati (in work, preliminare, rilasciato, pubbliche, private,
progetto)

Tracciabilit

Si intende la capacit di
risalire, attraverso opportuna
documentazione, allorigine di
un prodotto o di un semilavorato
Albero della tracciabilit

Requisito
iniziale

Caso duso

Specifica dei requisiti


funzionali e non
funzionali

Progetto
architetturale

Specifica di
progetto

Sorgente del
modulo

27

Test di
integrazione

Test unitario

Manuale
tecnico

Manuale
utente

Storyboard

Prototipo GUI

Documentazi
one di
collaudo

Documentazi
one di
installazione

Modello
grafico
software

Modello
grafico
manuale
utente

Generazione automatica
dei documenti
Efficienza ed efficacia

28

Generazione automatica dei documenti

Se si documenta opportunamente il progetto si ha una


tracciabilit completa del prodotto software e
maggiore qualit
Automatismo nel processo di creazione delle parti
ripetitive della documentazione
Non trascurabile
Codice sorgente: molte piattaforme di sviluppo
software includono strumenti di generazione automatica
della documentazione a partire dal codice sorgente
opportunamente commentato. Esempio Javadoc.
Durante la fase di analisi vengono prodotti schemi,
modelli, diagrammi. Devono essere inclusi in
opportuni documenti che ne spiegano le scelte
progettuali. Consentono la generazione automatica.
Esempio: White Star UML.

29