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!
;-) Leggi questo articolo...

White Paper di scenario: un esempio interessante

Vi segnalo un esempio interessante di White Paper di scenario.

E' un WP del 2008 che parla delle prospettive relative alle transazioni economiche sicure in ambito wireless/mobile. E' un argomento al quale sono particolarmente legato, perchè è stato oggetto della mia Tesi di Laurea nel 2002.

Ero largamente in anticipo sui tempi ma oggi si stanno sperimentando diverse architetture hardware/software finalizzate a realizzare pagamenti e transazioni per mezzo di terminali mobili, come i moderni smartphone. In questo White Paper vengono illustrati gli scenari più interessanti e le loro diverse caratteristiche.

L'approccio è del tutto in linea con quanto vi avevo segnalato in un post precedente.

Dal mio punto di vista presenta alcuni difetti, quali l'eccessiva lunghezza (34 pagine) e alcune soluzioni inessenziali (come la lista delle tabelle e delle figure riportata in coda all'indice del documento). Forse alcune parti potevano essere esposte in un modo più sintetico, ma la complessità dell'argomento non rende agevole una trattazione particolarmente asciutta.

Dateci un'occhiata, se volete farvi un'idea più precisa su queta tipologia di WP. Leggi questo articolo...

Quanto costa realizzare un White Paper?

Oggi mi sono imbattuto casualmente in un sito di sedicenti "professionisti" della documentazione tecnica che si propongono per la redazione di diverse tipologie di documenti e che per ogni tipologia propongono delle tariffe standard.

Incuriosito, sono andato sulla voce White Paper, dove ho letto che per realizzare un WP necessitano 55 Euro + IVA per cartella (un foglio formato A4, 1800 battute (30 righe da 60 caratteri), spazi inclusi) e che i tempi di realizzazione oscillano tra i 7 e i 10 giorni.

Sono sempre molto ammirato da chi dimostra di avere le idee così chiare.
Ma avrei voglia di porre qualche domanda.

COME SI FA A PROMETTERE UN TEMPO DI CONSEGNA DI 7-10 GIORNI?

La raccolta dei dati per realizzare un WP può essere molto onerosa.
Tipicamente, richiede la necessità di intervistare i tecnici che hanno elaborato la soluzione da illustrare nel WP, leggere e selezionare tutta la documentazione disponibile sviluppata fino a quel momento, analizzare i dati che gli analisti del settore hanno elaborato sull'argomento.
Solo questa fase può richiedere almeno 5-7 giorni di lavoro, nella migliore delle ipotesi.

Poi bisogna abbozzare la prima stesura, realizzare se necessario i grafici e le tabelle finalizzate a far emergere le informazioni significative, individuare e sottolineare nel modo più efficace i punti salienti della soluzione. Il tutto deve essere organizzato nell'ambito di una stesura sintetica e ben equilibrata tra le diverse parti tipiche della struttura di un WP.
Anche questa fase può richiedere ragionevolmente almeno altri 5 giorni di lavoro.

Poi c'è la fase di rilettura di tutto quanto già realizzato che sovente richiede di intervenire sul 10-20% del testo già prodotto, per limare tutto ciò che non serve o aggiungere qualche elemento che nella prima fase era stato omesso. Eventualmente, qualora lo si ritenga opportuno, si può integrare nel WP un Case Study che descriva una situazione reale in cui la soluzione in oggetto è già stata approntata.

Infine, c'è da curare tutta la parte che riguarda il layout grafico vero e proprio, che supporta i contenuti e guida il lettore dall'introduzione alle conclusioni.

Appare evidente che anche indicare un tempo realizzativo complessivo di 15 giorni, rappresenta in molti casi un esercizio di sfrenato ottimismo!

E POI 7-10 GIORNI PER QUALSIASI TIPO DI WP?

Un WP comparativo può richiedere un grande lavoro iniziale di acquisizione dati e le comparazioni vanno suffragate da dati di riscontro, che vanno anch'essi acquisti, studiati e valutati; quindi vanno messi in relazione, elaborando opportunamente grafici e tabelle.

Un WP sullo stato dell'arte di una soluzione può essere più agevole se siete già ben introdotti nel campo applicativo in cui si colloca tale soluzione, ma se per voi è un campo del tutto nuovo può richiedere un tempo difficilmente prevedibile.

E SU QUALSIASI ARGOMENTO?

Io sono un Ingegnere Informatico, ho una certa esperienza e per me scrivere un WP su soluzioni di sicurezza informatica o altre tematiche tipiche dell'ambito ICT può risultare abbastanza agevole. Ma se mi chiedessero un WP comparativo tra diversi modelli di trattori agricoli, mi richiederebbe un impegno e uno sviluppo temporale sicuramente maggiore, perchè dovrei indagare un ambito nuovo rispetto a quello della mia formazione specifica.

E PER QUALE TARGET?

A partire da una certa soluzione che ne costituisce l'oggetto, è ben diverso strutturare un WP che deve essere letto da un tecnico rispetto a quello che invece è indirizzato ad un analista o ad un dirigente amministrativo.

Potrei continuare, ma mi taccio.

E tacendo sorvolo sul problema della tariffazione, che non può essere stabilita in maniera standardizzata ed aprioristica.

Se quando scrivo un WP mi limito a fare un brutale lavoro di copia&incolla di materiale già pronto, 55 Euro + IVA per cartella è un furto!

Ma se devo elaborare un grafico concettuale legando insieme dati faticosamente raccolti da fonti diverse ed autorevoli, potrei impiegare anche 2 giorni per scrivere QUELLA singola pagina/cartella e in tal caso la tariffa sopraindicata sarebbe assolutamente insufficente.

Quindi lascio ai suddetti sedicenti "professionisti" le loro ingenue certezze calendariali e tariffarie e rimango convinto che la qualità richiede tempo ma alla fine viene premiata da chi la sa apprezzare.

Tuttavia credo che ritornerò sull'argomento più generale dei costi della documentazione, perchè mi rendo conto che poi questo è un nervo sempre scoperto nel rapporto tra il TW e il committente, specialmente nell'ambito della libera professione e della consulenza.
Leggi questo articolo...

L'uso dell'accento: regole sui monosillabi

In italiano le regole sugli accenti derivano sostanzialmente dall’uso prevalente consolidato, più che da motivazioni logiche; in generale è buona norma evitare di apporre l’accento se non è necessario.

L’accento distintivo serve a definire il valore grammaticale di un monosillabo, distinguendolo dagli omografi, per renderne esplicito il significato.

Se volessimo adottare una regola “riassuntiva” sui monosillabi, efficace nella maggiorparte dei casi, potremmo enunciarla così:

- un monosillabo è accentato se può avere due significati diversi;
- si accenta, tra i due, il verbo;
- se nessuno dei due monosillabi è un verbo, si accenta quello meno usato;
- se un monosillabo ha solo un significato, non si accenta mai.

Questa regola può essere utile in molti casi ma contempla delle eccezioni, come quelle relative alle note musicali.

Ad esempio, consideriamo la frase:

Il nostro Re ha molto apprezzato la Sinfonia in Re minore che il pianista ha appena eseguito.

E’ evidente che non c’è ambiguità tra il primo Re (inteso come sovrano) ed il secondo Re (inteso come nota musicale), quindi non c’è bisogno di apporre l’accento su uno dei due Re!

La tabella seguente indica l’uso prevalente relativo ai monosillabi elencati nella prima colonna a sinsitra:


La tabella non è esaustiva di tutti i casi possibili, ma riassume “l’uso consueto” per i monosillabi più comuni; unitamente alla regola sopracitata, fornisce una “bussola” per orientarci nella maggiorparte dei casi, ma in alcuni casi ci possono essere delle eccezioni.

Un esempio?

La Grammatica Italiana di Luca Serianni, l’Accademia della Crusca e il Dizionario Treccani concordano nell’indicare che "su" non prende mai l’accento.
Tuttavia in alcuni casi potreste trovare sù (avverbio) distinto da su (preposizione).

Non c'era che da tirar sù lo sportello della gabbia più piccola. (Pirandello)

In questo caso, se si fosse usato il su non accentato, era possibile fraintedere il significato della frase? Evidentemente no.
Se vi attenete alla tabella sicuramente non sbagliate ed eventuali eccezioni non fanno che confermare la proverbiale regola!

Altro esempio?

Giacomo Leopardi utilizza nella poesia A sé stesso il "sé" accentato prima di "stesso".

Per un certo periodo si è diffusa l’indicazione che “se stesso” o “se medesimo” si potesse scrivere omettendo l’accento sul se. Oggi questa posizione è giudicata un’inutile complicazione e si consiglia di mantenere comunque l’accento, come indicato in tabella.

Concludendo, l’uso dell’accento distintivo va valutato solo nei casi in cui serve effettivamente a dirimere una situazione ambigua.
Leggi questo articolo...