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...

L'uso dell'accento: parte prima

L'uso dell'accento è molto meno banale di quanto si possa immaginare.

Tralasciamo la casistica più ridicola e deteriore in cui rientrano tutti coloro che NON USANO GLI ACCENTI, "...perchè questa è una relazione tecnica, mica un romanzo!".

La scrittura tecnica è un particolare tipo di scrittura, che riponde a criteri e regole precise, ma sempre di scrittura in lingua italiana trattasi, quindi non esentata dal rispettare le regole della lingua italiana medesima!

E veniamo a noi che invece gli accenti li usiamo e spesso li sbagliamo, io per primo, specialmente quando non abbiamo tempo per ricontrollare accuratamente il testo dopo averlo scritto magari un po' troppo velocemente.

Operiamo una prima grande distinzione tra accento GRAVE ed accento ACUTO.

L'accento GRAVE caratterizza le parole che richiedono una pronuncia "aperta": narghilè, piè, caffè, canapè, cioè...
La grafia dell'accento grave è inclinata a sinistra: à, è, ì, ò ù.

L'accento ACUTO caratterizza le parole con pronuncia "chiusa": perché, ventitré, nonché, viceré, poté, mercé...
La sua grafia è inclinata a destra.

Le vocali a, i, o, u vogliono sempre l'accento GRAVE se sono poste al termine di una parola accentata.

Es.

- andrò in città
- vedrò papà
- farò così.

Ecco alcuni esempi in cui la vocale finale 'e' vuole l'accento GRAVE:

- verbo essere: è
- nomi di origine straniera: caffè, narghilè, tè
- nomi propri: Noè, Giosuè
- nelle parole: cioè, ahimè, ohimè, piè

Altri esempi in cui la vocale finale 'e' vuole l'accento ACUTO:

- nel passato remoto: poté, ripeté
- nei composti di che: perché, affinché, benché
- nei composti di tre: ventitré
- nei composti di re: viceré

Una schematizzazione a parte merita l'uso dell'accento distintivo sui monosillabi, ma ne parleremo nel prossimo post.
Leggi questo articolo...

Idee per il Low Cost Marketing

Nel mese di Giugno sono stato contattato da Cristina Mariani Barlow, una consulente di marketing e scrittrice che ha apprezzato i miei post inerenti alla realizzazione dei White Paper.

Cristina è anche l'autrice di un blog interessante, Marketing Low Cost.

In questo blog Cristina propone molti spunti per le piccole e medie aziende che spesso ritengono di non poter disporre delle risorse per impiantare una piano di marketing "tradizionale".

L'idea centrale del blog è quella che è possibile realizzare iniziative efficaci di marketing anche a basso costo, sfruttando strategie e strumenti spesso gratuiti ed innovativi.

Vi consiglio di darci un'occhiata.

Tenete presente che la comunicazione tecnica e la comunicazione di marketing sono due tipologie di comunicazione distinte che hanno la loro specificità ma che spesso si toccano e si intersecano. Ed è per questo che a volte mi piace "sconfinare". Leggi questo articolo...

Sono ritornato... le vacanze sono finite.

Eccomi di ritorno dal viaggio di nozze in Egitto.

Nella foto seguente mi vedete immerso nel Mar Rosso, in quel di Marsa Alam, mentre faccio le mie prime esperienze di snorkeling e mia moglie mi fotografa:


Anche per dei neofiti come noi, il Mar Rosso ha riservato sorprese mozzafiato.
Pur senza avventurarci oltre la barriera corallina, abbiamo potuto ammirare molti pesci diversi e spettacoli come quelli illustrati nella foto successiva:


Nella foto seguente invece sono al Tempio di Horus, nella città di Edfu, ai piedi della statua del falco che impersona il Dio Horus:


Ogni tanto è necessario staccare la spina e fare il pieno di sole, mare, riposo, energia fisica e psichica. E poi si ricomincia. Con molte idee che spero possano essere utili e interessanti.
A presto. Leggi questo articolo...

Il 19 Giugno mi sposo!

Ebbene si, dopo 44 anni anche io ho trovato un cuore di donna che ha fermato la mia spesso disordinata ricerca dell'altra metà della mela. Dopo circa 7 anni di convivenza, ci sposiamo.

In un certo qual modo è come se si sposassero anche due Blog, L'Artigiano di Babele e Puntodivistaceliaco, il blog di Patrizia. In questo mese ho scritto poco, anche se ho molti post in fieri.

Ma si sa che i preparativi per il matrimonio sono una corsa ad ostacoli e mi hanno sottratto tempo. Cercherò di recuperare al ritorno dal viaggio di nozze. Ciaooo!!!

Leggi questo articolo...

DDL Intercettazioni: anche oggi mi vergogno di essere italiano

Oggi scrivo un post dissonante con i temi specifici di questo blog.
Oggi non mi va di parlare di manuali, di grafica, di tabelle e di White Paper.
Oggi sono prima di tutto un cittadino e poi un blogger che, come accade ormai da molto tempo, si ritrova a vergognarsi dell'operato del proprio governo e non si riconosce nei principi e nella lettera del DDL sulle Intercettazioni che rappresenta un ulteriore passo verso la distruzione dello stato di diritto, della legalità e della dignità di questo paese.
Voglio rimarcare solo alcuni punti.

Si è partiti dall'idea di equilibrare un presunto eccesso relativo alla PUBBLICAZIONE delle intercettazioni (del resto già punibile in base alle leggi vigenti) per realizzare una legge che LIMITA PESANTEMENTE la possibilità di EFFETTUARE intercettazioni telefoniche e ambientali.

Si impongono INAUDITI E RIDICOLI limiti temporali agli inquirenti e pene sproporzionate a giornalisti ed editori. MA UDITE UDITE... vengono imposti taluni vincoli di rettifica ANCHE AI BLOGGER!!!

Infatti, nel famigerato articolo 28 del DDL si enuncia, tra l'altro, quanto segue:

"Per i siti informatici, le dichiarazioni o le rettifiche sono pubblicate, entro quarantotto ore dalla richiesta, con le stesse caratteristiche grafiche, la stessa metodologia di accesso al sito e la stessa visibilità della notizia cui si riferiscono"

Un BLOG è assimilabile ad un sito informatico? A lume di naso direi di si, anche se la dicitura "sito informatico" è quanto meno e VOLUTAMENTE imprecisa. Volendo fare l'Ingegnere, vorrei suggerire a lor cialtroni che forse sarebbe stato utile distinguere fra un server FTP, un sito Web e una rete virtuale peer to peer... ma tanto non avrebbero capito nulla di cosa stavo dicendo e non intendo dare loro dei suggerimenti.

Il mio BLOG NON E' UNA TESTATA GIORNALISTICA ED IO NON SONO UN GIORNALISTA!

Ma in base a tale legge, se domani dovessi esprimere una critica ragionata su un prodotto di un'azienda X, l'azienda X mi potrebbe chiedere una rettifica che sarei obbligato a pubblicare entro le 48 ore!

E che c'entra questo CON LA LEGGE SULLE INTERCETTAZIONI?

Se lo scopo era quello di limitare la libertà di espressione dei BLOG "politici", FORSE ci sono riusciti e questo mi fa schifo.
Ma per colpire la libertà d'espressione politica della rete, colpiscono alla cieca anche QUALSIASI ALTRO TIPO DI BLOG, compreso i BLOG "tecnico-professionali" come il mio e questo è ridicolo!

Fortunatamente, sono sufficentemente incompetenti e chi pratica la rete sa che ci sono diversi workaround disponibili.

Ma "il sonno della ragione genera mostri", quindi vediamo di SVEGLIARCI! Leggi questo articolo...

I labirinti della scrittura

Non ho mai studiato volentieri le regole della grammatica. Ho sempre avuto un buon "orecchio" e quando sentivo che "la frase girava bene", ero confidente che quello che avevo scritto poteva essere anche grammaticalmente corretto. A scuola sono sempre andato bene in italiano e il tema in classe, generatore d'ansia per molti miei compagni, per me scivolava sempre via con semplicità.

La grammatica non la capivo o forse non me l'hanno mai saputa spiegare; in ultima analisi, se scrivevo bene senza saper fare l'analisi logica del periodo, voleva dire che studiare la grammatica era una perdita di tempo.

Ma a volte la linea più breve tra due punti è l'arabesco... e io che preferivo risolvere un problema di Matematica o di Fisica invece di analizzare una frase di 3 righe, dopo essermi laureato in Ingegneria, mi sono ritrovato a fare della scrittura la mia professione.

La scrittura tecnica è un particolare tipo di scrittura, con una sua specificità molto spiccata. Ma con l'esperienza mi sono ritrovato a dover ammettere che le regole grammaticali e sintattiche sono oltremodo importanti anche in un documento tecnico.

Anzi forse lo sono di più di quanto non si pensi PROPRIO PERCHE' SI TRATTA DI UN DOCUMENTO TECNICO, dove si richiede sempre il massimo della sintesi e dell'efficacia comunicativa.

Con questo post inauguro una nuova sezione del blog in cui cercherò di fornire alcuni spunti di chiarezza, senza alcuna pretesa di esaurire il tema.

E credetemi: NON E' MAI TROPPO TARDI! :-) Leggi questo articolo...