Saper scrivere... il Manuale d'Installazione.

Il Manuale d'Installazione di un prodotto/applicazione software è uno dei documenti più comuni che ognuno di noi ha avuto modo di utilizzare almeno una volta nella vita e sul quale, non di rado, abbiamo anche imprecato laddove risultava poco usabile, non chiaro o incompleto.

Lo scopo del Manuale d'Installazione è quello di fornire tutte le indicazioni necessarie, nel modo più chiaro e sintetico possibile, per installare correttamente un'applicazione.

Anche se alcuni elementi di questo documento possono variare in base alla tipologia di software in esame, è possibile comunque fornire una descrizione abbastanza precisa della sua struttura generale che può essere ritenuta valida nella gran parte dei casi.

Lo schema di riferimento che vi descrivo è formato da 10 sezioni:

- INTRODUZIONE
- PREREQUISITI HARDWARE
- PREREQUISITI SOFTWARE
- COMPATIBILITA' DEL BROWSER (se necessario)
- DESCRIZIONE DELLA DISTRIBUZIONE
- INSTALLAZIONE DEL DATA BASE (se necessario)
- DEPLOY DEI MODULI SULL'APPLICATION SERVER (se necessario)
- CONFIGURAZIONE DELL'APPLICAZIONE (se necessario)
- RISOLUZIONE DEI PROBLEMI
- SUPPORTO ED ASSISTENZA


Analizziamo brevemente ognuna di queste sezioni.

INTRODUZIONE
In questa prima sezione si deve fornire una breve descrizone del prodotto/applicazione.
Al termine di questa sezione può essere eventualmente specificata una frase che ribadiscce la natura e lo scopo del documento:

"Lo scopo di questo documento è quello di descrivere la procedura d’installazione del XYZManager ed è rivolto alle figure amministrative/operative che devono intervenire ai fini dell’installazione del prodotto. Ognuna di queste figure potrà consultare questo documento, utilizzandolo per quanto concerne le prerogative di sua competenza. Tutto ciò che necessita all’installazione del prodotto è specificato in questo manuale".


PREREQUISITI HARDWARE
Qui vanno specificate, se necessario, le caratteristiche minime dell'hardware necessario per poter eseguire l'applicazione (es. 512 MB di memoria centrale RAM, configurazioni LAN/WAN,... ).


PREREQUISITI SOFTWARE
Analogamente al caso precedente, vanno indicati tutti i moduli software che devono essere installati sulla macchina prima di procedere all'installazione dell'applicazione in esame.
Tipicamente, tra questi elementi va sempre specificato il Sistema Operativo ospite, con la
relativa versione. Altri elementi da specificare sono eventuali librerie necessarie all'applicazione (OPEN SSL, OPEN LDAP, ...). In generale, vanno specificati tutti i moduli software necessari che non verranno installati sulla macchina dal processo d'installazione stesso e senza i quali l'applicazione non potrà essere eseguita.

Di seguito è indicata una tabella d'esempio molto semplice che può essere utilizzata a tale scopo:



COMPATIBILITA' DEL BROWSER (se necessario)
Se l'applicazione in questione è un'applicazione Web, è necessario indicare con quali browser e relative versioni è possibile eseguirla.
Questa informazione può essere indicata anche tra i prerequisiti software.


DESCRIZIONE DELLA DISTRIBUZIONE
Un'applicazione software può essere distribuita in diversi modi: su un supporto magnetico, ottico (CD-ROM), su una USB Key, via Web o in altri modi. Indipendentemente dalla modalità e dal supporto fisico, la distribuzione di un software viene organizzata in una gerarchia di cartelle e file che racchiudono tutte le compnenti dell'applicazione.
Questa organizzazione deve essere descritta dettagliatamente, per fornire all'utente tutte le informazioni sulle diverse componenti coinvolte nel processo d'installazione.


INSTALLAZIONE DEL DB (se necessario)
In questa sezione vanno specificate tutte le operazioni necessarie all'installazione del DB.
Questa è una fase generalmente molto delicata, di solito effettuata da tecnici molto specializzati.
Io consiglo sempre di sottolineare questo elemento con una nota del tipo indicato di seguito:


L'installazione di un DB generalmente procede attraverso l'esecuzione di un certo numero di script SQL.
Questa fase deve essere illustrata in modalità "step by step", come mostrato nel breve esempio seguente:

1. Collegarsi al DB con le credenziali di amministratore.

2. Aprire la cartella SCRIPTS fornita con la distribuzione del prodotto.

3. Eseguire il file SCRIPT_01.sql.

4. Eseguire il file SCRIPT_02.sql.

...

Se l'installazione procede in un'altra modalità, bisogna comunque dettagliare tutti i passaggi essenziali.


DEPLOY DELLE COMPONENTI SULL'APPLICATION SERVER (se necessario)
Ogni fase di questa sezione deve essere illustrata in modalità "step by step".
Per ogni componente si deve indicare la posizione d'origine, all'interno della distribuzione di partenza del prodotto, e la posizione finale in cui va collocata, con la descrizione di ogni azione necessaria a tale scopo.


CONFIGURAZIONE DELL'APPLICAZIONE (se necessario)
Dopo aver definito il posizionamento delle diverse componenti dell'applicazione, talvolta è necessario intervenire su alcune di esse per apportare delle modifiche alla configurazione di default.

Questa fase può essere effettuata con l'ausilio di appositi tool o modificando direttamente i file di configurazione previsti a tale scopo. Anche questa fase deve essere attentamente dettagliata.


RISOLUZIONE DEI PROBLEMI
Durante il processo d'installazione, possono verificarsi dei problemi originati da numerose "condizioni d'errore".
Molte di queste condizioni sono note ai progettisti e un buon manuale dovrebbe fornire una descrizione della condizione d'errore e la sua risoluzione, eventualmente supportata da altre informazioni (screenshot, tabelle, ...).


SUPPORTO ED ASSISTENZA
In quest'ultima sezione vanno indicati i riferimenti (email, telefono, ...) dello staff che si occupa di fornire assistenza e supporto tecnico al cliente.

..............

Come sempre, le schematizzazioni che vi propongo sono valide in molti casi ma non possono essere prese "tal quali" ed utilizzate meccanicamente in ogni situazione.
Caso per caso, dovete decidere voi se adattare o specializzare la struttura generale, se togliere una sezione o aggiungerne un'altra, per ottimizzare la vostra soluzione.

Se siete interessati ad ulteriori approfondimenti, sapete dove trovarmi!
;-)

Condividi

Articoli correlati per categorie