Documentazione del progetto

 

Tipi di documentazione

 

Documentazione amministrativa: è l’insieme 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 d’acquisto

• Richieste di acquisto, preventivi, ordini, conferme d’ordine

• Verbali di consegna e ricevute di pagamento

 

Documentazione di processo: è l’insieme 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.

 

Documentazione tecnica del progetto: è l’insieme 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

 

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 dell’interfaccia 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 all’utente un esempio di utilizzo del software

 

Documentazione per l’utente:

 

• Installazione

• Configurazione

• Utilizzo

• Risoluzione dei problemi: panoramica dei problemi più frequenti e relativa soluzione, FAQ, help online o cartaceo

• Diritti d’autore: informazioni legali, licenza e garanzia

• Contatti: assistenza tecnica e supporto

 

Enti per gli standard di documentazione

 

Governo:  tramite le normative civilistiche, fiscali e/o la legislazione nazionale e locale

 

ISO: International Organization for Standardization

 

• Requisiti

• Specificazioni

• Linee guida per gli standard

 

IEC: International Electrotechnical Commission

• ISO/IEC 12207: per la gestione del Ciclo di vita del software

 

IEEE: Institute of Electrical and Electronics Engineers

 

• IEEE 802:  standard per le reti locali (LAN) e per le reti 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

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Forme della documentazione

 

• Documentazione cartacea

 

• Documentazione in formato elettronico

Pdf

Web

Help proprietari

 

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 l’impostazione di base del documento.

 

• 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à dell’oggetto a cui fa riferimento

• Inserimento di parti significative

 

Processo di approvazione: sequenza di azioni di verifica da parte delle figure coinvolte. Si usa un ciclo approvativo (approval workflow): interno, normato e noto, si usa un diagramma degli stati. Il ciclo approvativo deve essere:

 

• Documentato

• Archiviato

• Reso accessibile a tutti i soggetti coinvolti

 

Possibili allegati prodotti da altre organizzazioni faranno parte della raccolta (o libreria). Non sono soggetti all’approval workflow. Il servizio aziendale di archiviazione (ECM: Enterprice Content Management System cioè Sistema di Gestione dei Contenuti Aziendali) dei documenti deve:

 

• 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 l’accesso

• Consentire l’applicazione di un workflow approvativo

 

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 d’uso GPL (cioè uso in forma gratuita ed installabile su Windows) 

 

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 l’identificazione degli utenti

-Consentire l’applicazione di un workflow approvativo

 

Redazione di un manuale utente

 

Attività di elaborazione testi che documenti l’utilizzo di un programma da parte di tutte le tipologie di utente

User experience:  rappresentare l’esperienza che si ha durante l’uso del programma

Esempio HelpNDoc e Wiki

Aspetti organizzativi

 

-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 all’utente)

 

Contenuti:

 

-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

 

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 l’aspetto 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.

 

Codifica dei documenti e tracciabilità

 

-È la sua carta d’identità, indica univocamente:

 

-Il contesto produttivo

-La storia e l’evoluzione 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

*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)

 

-Si intende la capacità di risalire, attraverso opportuna documentazione, all’origine di un prodotto o di un semilavorato

-Albero della tracciabilità

 

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.