venerdì 31 dicembre 2010

Bilancio del blog nel 2010

L’ultimo post del 2010 è ovviamente dedicato ai bilanci.

L’idea del blog è nata il 1° Gennaio 2009, il primo post era in linea il 15 Febbraio. Il bilancio del 2009 fu sorprendente, rispetto alle mie aspettative iniziali.

Il 2010 è stato l'anno del consolidamento.

Il blog si è confermato un'eccezionale e necessaria "palestra" di scrittura e comunicazione; mi ha fornito riscontri incoraggianti sul mercato che si sta sviluppando in Italia nel campo della comunicazione tecnica;
mi ha dato la possibilità di un confronto con professionisti del settore, più esperti di me; mi ha dato spunti per approfondire aspetti del mio lavoro, senza la pressione tipica che spesso detta il ritmo delle nostre quotidiane necessità professionali.

Senza il blog non avrei avuto la soddisfazione di essere citato da Cristina Mariani, che ringrazio ancora per l'apprezzamento, nel suo ultimo libro "Comunicazione low cost".

Voglio usare anche quest'anno l'immagine che avevo coniato alla fine del 2009: il blog ti obbliga a dedicare maggiore attenzione a tutto ciò che ha che fare con il tuo mestiere di comunicatore tecnico e con la scrittura in generale… un po’ come quell’amico che ti trascina a fare jogging perché magari da solo cederesti alla pigrizia.

E ora per gli appassionati dei dettagli, qualche elemento numerico.
Di seguito potete vedere “l’encefalogrammma” del blog durante il 2010:


Un inizio vivace, un paio di periodi "stanchi", in Aprile ed Agosto, poi da Settembre fino alla fine un sensibile e prolungato incremento di contatti,con più di un picco robusto e, per fortuna, mai “andamento piatto”!

I numeri vanno presi con le molle, in quanto il rilevamento non è sempre affidabilissmo, ma diciamo che applicando una variazione del 5%, per eccesso o per difetto, diventano numeri solidi.

Circa 13.200 visitatori; di questi, circa 3.200 ritornano abitualmente sul blog.
Il tempo medio di visita si aggira intorno ai 3’10” , per tutti i 13.200 visitatori.
I nuovi visitatori indugiano per circa 1’40”, quelli che ritornano lo navigano per circa 8’10” .
Le pagine visitate sono circa 27.000 ma se eliminiamo almeno il 20% di pagine che vengono accedute “per caso” e poi subito abbandonate, diciamo che scendiamo a poco meno di 22.000.

Ho ricevuto visite da 70 paesi diversi, anche se il 90% (circa 12.100) è concentrato in Italia:




Per un blog scritto in italiano, che si occupa di una professione di nicchia, nulla di strano. La Svizzera è il secondo paese nella classifica degli accessi.

I numeri sono del tutto analoghi a quelli esposti nell'ultimo post del 2009 e credo che questa osservazione sia confortante.

Possiamo chiudere qui.
Ci vediamo domani, nel 2011, che vi auguro pieno di salute, lavoro e serenità, che sono sempre e comunque le cose più importanti.
Ciao.
Leggi questo articolo...

mercoledì 29 dicembre 2010

Prevenire gli incidenti sul lavoro: anche con la documentazione tecnica

Vi segnalo un articolo (fonte Unistudio) che deve far pensare.

Secondo i dati INAIL, nel 2009 gli infortuni sul lavoro ufficialmente denunciati sarebbero 790.000. Di questi, molti sono risultati mortali.

L’uso errato di macchine e impianti rappresenta spesso una delle cause di tali incidenti. Troppo spesso si tiene in considerazione la sicurezza della macchina solamente nella fase di progettazione o costruzione. Ma anche se perfettamente funzionanti, le macchine possono essere pericolose se non vengono usate in modo corretto e secondo le indicazioni d'uso fornite dal costruttore.

Per tutte le macchine che ricadono nelle indicazioni della Direttiva Macchine 98/37/CE, il Manuale d’uso e manutenzione deve essere considerato un vero e proprio strumento di prevenzione degli infortuni.

Avevo accennato a questo tema nel post del 20 Novembre 2010, in particolare ai punti 2 e 3.
Mi riprometto di approfondire l'argomento in futuro, ma è evidente che, specialmente in certi settori, comprimere i costi di sviluppo della documentazione tecnica e sulla formazione delle persone che devono utilizzare certi macchinari, è una scelta estremamente discutibile se non drammaticamente miope.

Philip Kotler, uno dei "guru" mondiali del marketing, ha detto una frase molto interessante:
"Le aziende si preoccupano troppo di quanto costa fare. Dovrebbero preoccuparsi, invece, di quanto costa non fare".

Questa frase si adatta benissimo all'argomento del post, ma temo che la riprenderò in futuro perchè è ora di iniziare tutti insieme a fare dei ragionamenti sui costi nascosti del NON FARE, della NON QUALITA', della NON INNOVAZIONE, della NON SICUREZZA e di altro ancora che in qualche modo ci riguarda, indipendentemente dal lavoro che facciamo.
Leggi questo articolo...

martedì 28 dicembre 2010

Saper scrivere è anche... non scrivere più di quanto basta!

Asciugare, ridurre, semplificare senza distorcere il senso di una frase, sintetizzare, togliere, togliere tutto ciò che non serve. Il mestiere del comunicatore tecnico è un mestiere "a togliere"; partire dal blocco di marmo e togliere tutto quello che è "in più" e che racchiude "la statua", il concetto che vogliamo sia visibile a tutti.

Lo pensava Michelangelo quando scolpiva, lo hanno pensato moltissimi grandi scrittori, a maggior ragione lo deve pensare un comunicatore tecnico, che non scrive romanzi o altri tipi di componimenti creativi, ma scrive per aiutare altri a capire concetti da utilizzare nel loro lavoro.

Di queste cose, in quasi due anni, vi ho parlato molte volte ed ho scritto più di un post sull'argomento, racchiusi nella sezione Esercizi di riscrittura.

Ma stasera vi segnalo un post interessante di Leslie O'Flahavan, in cui si dimostra come sia possibile riscrivere un testo usando solo la metà delle parole rispetto alla stesura originale.

Provateci, è un esercizio molto utile. Prendete un testo dal Web, da un sito qualsiasi, su un argomento a caso (magari eviterei un trattato sulle particelle sub-nucleari...). Provate a riscriverlo con la metà delle parole, facendo attenzione, ovviamente, a non stravolgerne il senso. Vi accorgerete che Leslie ed io abbiamo ragione, cioè che quasi sempre è possibile migliorare un testo, asciugandolo da tutto ciò che è inessenziale.

Provateci e fatemi sapere.
Leggi questo articolo...

venerdì 24 dicembre 2010

BUONE FESTE!

Abbiamo tutti bisogno di riposo e di speranze. Un augurio sincero di salute, lavoro e serenità a tutti i miei lettori.


E un paio di libri da regalare a chi vi sta a cuore.

Uno è un classico, "Lezioni americane" di Italo Calvino.
Per chi ama scrivere è uno di quei libri che SI DEVONO leggere. La lezione sulla "leggerezza", in particolare, dovrebbe essere mandata a memoria, come una preghiera. E chi scrive documentazione tecnica dovrebbe applicarla ogni volta.

L'altro è "Palazzo Yacoubian", un libro che ho letto di recente, di un grande scrittore egiziano, Ala Al-Aswani. Per chi ama o vuole conoscere meglio l'Egitto, aldilà degli stereotipi commerciali fabbricati per i turisti occidentali. Leggi questo articolo...

domenica 19 dicembre 2010

La Qualità nella documentazione tecnica: lo scalpello di Michelangelo... o la sua mente?

Mi sono laureato in Ingegneria a La Sapienza di Roma, nella storica sede di S.Pietro in Vincoli. La facoltà è ospitata in uno splendido edificio che in origine era un convento, adiacente ad una delle più antiche basiliche romane in cui è ospitato "Il Mosè" di Michelangelo, una delle sue opere più maestose.
photo © 2005 Vento di Grecale | more info (via: Wylio)

Più volte ho avuto occasione di ammirarlo ed ogni volta c'era un particolare che mi sorprendeva: una piega del panneggio che sembrava morbida come la seta, una vena che sembrava pulsare nel possente braccio sinistro, un particolare della barba o del viso che sembravano in movimento.

Quale tecnologia ha prodotto questa meraviglia? In apparenza, un banale scalpello. Simile a quelli che ho nella cassetta degli attrezzi per i lavori domestici.

C'è qualcosa di più rozzo di uno scalpello che vi possa venire in mente? Non lo so, forse si, ma poca roba. Eppure, messo nelle mani di un genio dell'umanità, ha prodotto qualcosa di meraviglioso. Mentre nelle mie mani al massimo serve a far da leva per sollevare il tombino di cemento che ho in giardino.

MA TUTTO QUESTO COSA A CHE FARE CON IL TECHNICAL WRITING?

Nelle offerte di lavoro che ricevo attraverso i siti di JobSearch, specialmente negli ultimi 2-3 anni, sono sempre più pressanti le richieste inerenti alla conoscenza di strumenti di Authoring largamente utilizzati (RoboHelp, FrameMaker, DocBook, HTML Help Workshop, DITA, ...) che negli ultimi 10 anni si sono progressivamente diffusi, specialmente nelle aziende medio-grandi.

Tali prodotti sono divenuti via via sempre più versatili e dotati di un gran numero di possibilità.

Dispongono di funzionalità per la generazione automatica dell'indice di un manuale, per la memorizzazione dei contenuti in un DB,  per l'attività di importazione/esportazione di testo da/verso il formato XML, per la pubblicazione sul Web e nei diversi formati generalmente utilizzati dagli utenti, in particolare PDF.

Indubbiamente, facilitano le operazioni di riutilizzo e di aggiornamento dei contenuti.

Lo stesso contenuto posso "montarlo" in 5 "schemi" diversi che possono generare 5 documenti diversi.
Quindi lo scrivo una volta sola, eventualmente lo traduco nella lingua che mi interessa una volta sola e lo utilizzo in 5 situazioni diverse senza dover fare "copia e incolla" ma attraverso una procedura automatizzata.
Quando questo contenuto deve essere modificato, modifico "il master" e poi propago la modifica ovunque mi necessita con un semplice click.

BELLO NO? Bellissimo! MA FATE ATTENZIONE!

Non confondete lo scalpello di Michelangelo (i sistemi di Authoring) con la mano di Michelangelo, che sta attaccata al cervello di Michelangelo che ospita la fantasia visionaria ed il genio di Michelangelo!

In altri termini, è utile conoscere tecnologie che sono in grado di velocizzare e razionalizzare il processo di produzione della documentazione tecnica. Ma tali strumenti cosa sono, nella loro essenza?

Sono dei "montatori di contenuti". E se non sappiamo scrivere e strutturare "i contenuti", cioè se non conosciamo "il mestiere di scrivere" e non applichiamo i suoi fondamentali nella realizzazione di ogni singolo contenuto, poi potremo montarli e rimontarli come vogliamo, con tutti i prodotti di Authoring di questo mondo, ma otterremo sempre un risultato scadente.

Dobbiamo quindi riflettere sull'idea che gli strumenti possano, ingannevolmente, prendere il sopravvento sul “mestiere”, pericolo tanto più subdolo quando si incarna nella skill request che viene specificata in un'offerta di lavoro.

Infatti, sembra che si stia facendo strada l'idea che trovare lavoro come Technical Writer dipenda da quanti di questi strumenti è possibile elencare nel proprio CV. Frequentemente, nei forum, il dibattito è imperniato sugli strumenti e le tecnologie emergenti, sulle metodologie di misurazione del proprio rendimento lavorativo (in termini di "pagine al giorno" o "documenti in un mese" o altro ancora), mentre accade di rado che i temi siano lo sviluppo dei contenuti e la loro Qualità.

I vantaggi offerti dagli strumenti di Authoring sono indiscutibili ma, almeno per ora, non sono di grado di produrre contenuti. E' ancora necessario un redattore per creare i contenuti e lo scopo di questi strumenti è quello di rendere più efficente e veloce la produzione e l'aggiornamento su larga scala di molti documenti diversi. Tutto qui.

Del resto, a cosa serve usare i collegamenti ipertestuali o le funzioni di ricerca rapida per scorrere velocemente un documento, saltando da un punto all'altro, se poi l'utente non trova le informazioni che cercava, oppure se queste sono incomplete?

La documentazione di un prodotto, se è di buon livello, deve guidare con semplicità l'utente all'uso efficace del prodotto e poco conta che sia stata prodotta con RoboHelp o DITA o con un "primitivo scalpello" altrimenti noto come Microsoft Word.
Su nessun manuale ho mai visto la scritta “Sviluppato con il miglior strumento di Authoring in commercio”.
Non ho mai conosciuto un cliente che abbia espresso preferenze sugli strumenti utilizzati per realizzare un Installation Manual o un Tutorial.

Quindi usiamo gli strumenti per quello che sono, traendone cospicui vantaggi di ogni genere, ma non infiliamo "la scorciatoia concettuale" di pensare che la Qualità di un documento derivi dallo strumento che usiamo per realizzarlo.

Se fosse vero, con il mio scalpello potrei scolpire capolavori come "Il Mosè" ogni giorno.
Invece non mi succede mai... :-).
Leggi questo articolo...

venerdì 10 dicembre 2010

Bookmarks in the cloud

In questo periodo sto progettando un restyling del blog, voglio realizzare in sito professionale di auto-promozione, sto iniziando a lavorare per un nuovo cliente e sto sperimentando nuove idee.

Quindi sono in rete molte ore al giorno e quando vado su un sito che mi interessa lo navigo un po' e poi penso: "...questo ora lo registro tra i bookmark, poi ci torno con calma...".

Ma a volte capita di non avere il proprio portatile a disposizione, con tutti i bookmark ben classificati. Magari si accede ad Internet dallo smartphone o dal PC dell'albergo o da una postazione di un cliente e allora sarebbe bello avere i propri bookmark "in the cloud".

Instapaper vi consente, dopo una velocissima registrazione, di mantenere i siti visitati in una directory a voi dedicata.


Potete poi visualizzare i contenuti delle pagine Web che avete memorizzato da qualsiasi terminale (questo lo devo ancora verificare), anche in modalità ONLY TEXT se volete velocizzare il download delle pagine su terminali mobile.

Per salvare velocemente le pagine, vi mette a disposizione un bookmarklet che potete trascinare sulla barra dei bookmark del vostro browser. Ogni volta che una pagina vi interessa, premente il pulsante Read Later e la pagina sarà salvata sul server Web di Instapaper.

ATTENZIONE! NON SARA' "PER SEMPRE"!

L'idea è di un repository "temporaneo", quindi non viene data alcuna  garanzia esplicita che i vostri bookmark saranno mantenuti per i prossimi 30 anni! Ma del resto ciò sarebbe anche assurdo, data la natura stessa del Web. Diciamo che sono abbastanza confidente nel fatto che tra 6 mesi potrò trovare nel Web i bookmark che ho salvato ieri, e questo mi basta.

D'altro canto, se entro 6 mesi non trovo il tempo di visitare e classificare un sito che ritenevo interessante... vuol dire che non lo era!

Spero possa esservi utile.
Ciao.
Leggi questo articolo...

giovedì 9 dicembre 2010

Immagini free per i vostri post: Wylio

Quando si scrive un post, il potere evocativo delle immagini può essere di grande aiuto per catturare l'attenzione del lettore. Cercando in rete, ci si può imbattere in immagini coperte da copyright.

Ieri ho trovato un nuovo motore per la ricerca di immagini free, Wylio.
Tali immagini sono rese disponibili dagli autori sotto la licenza Creative Commons (uso non commerciale).

Per inserire l'immagine nella vosta pagina Web basta fare il copia-incolla di un brano di codice che già contiene i riferimenti al suo autore. Tali riferimenti sono posizionati proprio sotto il bordo inferiore dell'immagine e basterà cliccarli per ri-conoscerne la proprietà intellettuale.

Ed ecco un esmpio:

Free Happy Rainbow Water Droplet on Green Creative Commonsphoto © 2007 D. Sharon Pruitt | more info (via: Wylio)

Wylio consente l'accesso a decine di migliaia d'immagini, ho fatto alcuni test e sono molto soddisfatto, provate ad usarlo.

Se poi volete saperne di più sulla licenza Creative Commons, potete inizare da qui.
Leggi questo articolo...

Realizzare una buona Presentazione non è un pranzo di gala

Uno dei terreni più scoscesi dove si può misurare la capacità di un comunicatore tecnico è quello delle Presentazioni. Questi oggetti sono spesso elementi decisivi (insieme al White Paper e al Case Study) nel convincere un potenziale cliente ad adottare la nostra soluzione o prodotto.

Ma per qualche imperscrutabile motivo, si pensa che realizzare una Presentazione consista in una banale collezione di slide più o meno arrangiate, fatta in fretta e furia, realizzate facendo copia e incolla "al buio" di altro materiale aziendale, spesso pessimo anch'esso.

Io da anni vedo andare in giro Presentazioni risibili, che vanno benissimo per perdere clienti o, se in formato cartaceo, per accendere il camino a Natale.

Realizzare una buona Presentazone richiede notevole capacità ed io, avvertendo il disagio della mia ignoranza (come diceva un mio vecchio professore), cerco disperatamente di imparare da chi ne sa più di me.

Fortunatamente stavolta posso darvi due "dritte" molto italiane sull'argomento, che ritengo di altissimo profilo. In realtà una ve l'ho già data, la trovate nella sezione DA VISITARE e mi riferisco al blog di Giacomo Mason, www.presentazioniefficaci.wordpress.com.

Ma stamattina, andando in rete per cercare altre cose, mi sono imbattuto in un'altra gemma, il blog di Cristina Rigutto, www.tuttoslide.com. L'ho navigato per un pò e già mi è piaciuto, sia nello stile che nei contenuti.

Anche lei presto entrerà nella sezione DA VISITARE.

Certo, se mi fosse piaciuto vincere facile, potevo stendervi con due super-classici come www.presentationzen.com oppure http://beyondbulletpoints.com/.

Ma per una volta che possiamo disporre di risorse in lingua italiana pregiate ed interessanti, almeno stavolta ci sentiremo un pò meno "provincia dell'Impero".
Leggi questo articolo...

mercoledì 8 dicembre 2010

Case Study: risorse in rete

Nel post di Domenica scorsa vi ho parlato del Case Study, uno dei documenti più importanti nell'ambito dell'attività di supporto al marketing e alla prevendita di un prodotto/di una soluzione. Oggi vi fornisco alcuni link che potete navigare per approfondire l'argomento.

Steps on the flyover connecting the Case study Joint Pavilion Group areasphoto © 2010 Bo ( | more info (via: Wylio)

Premetto che le risorse più qualificate e numerose sono ovviamente in lingua inglese.

In italiano purtroppo c'è ben poco, con rare e sapienti eccezioni, prima fra tutte, come sempre, Luisa Carrada ed il suo Scrivere un Case Study. Io stesso sono partito dal post di Luisa e poi ho letto molto altro materiale.

Dal blog di Cristina Mariani potete leggere un altro post interessante. Cristina ha poi  ripreso l'argomento anche nel paragrafo 5.5 del suo ultimo libro - "Comunicazione low cost" - nel quale è presente anche un mio piccolo contributo sull'argomento White Paper.

Un ottima risorsa gratuita in italiano ce la fornisce la Cisco, con una collezione di Case Study relativi a diversi clienti. Ho scoperto questa risorsa dopo aver terminato il post precedente e mi sono accorto che la struttura dei loro CS è del tutto analoga a quella che vi ho suggerito io e questo mi conforta grandemente!

Ed ora alcuni spunti oltrefrontiera.

Dalla Harvard Business School ecco una ricca raccolta di Case Study prodotti dalla Harvard Business Publishing. Potete accedere a più di 13.000 titoli ma dovete acquistarli. La maggiorparte di essi può essere acquisita con meno di 7$. Con un piccolo investimento potete imparare come deve essere costruito un Case Study e in questo caso "l'insegnante" è veramente di alto livello.

Debbie Weil è una guru del Marketing e della comunicazione Web e ci fornisce il suo interessante approccio sull'argomento. 

Infine, un post su come scrivere un Case Study e molti link correlati per ulteriori riflessioni.

In rete potete trovare molto altro, queste sono solo le tracce iniziali di un cammino che potrete disegnare come vorrete.
Leggi questo articolo...

domenica 5 dicembre 2010

Saper scrivere... il Case Study (Success Story)

In alcuni post precedenti abbiamo analizzato il ruolo del White Paper nella comunicazione di marketing, soprattutto nell'attività di supporto alla pre-vendita di un prodotto/di una soluzione.

Il White Paper viene spesso indicato come uno strumento di comunicazione "orizzontale", perché generalmente analizza un prodotto/soluzione che possono essere utilizzati da diversi clienti.

Il Case Study è invece uno strumento "verticale", perchè il suo scopo è quello di focalizzare una particolare realizzazione per un particolare cliente.

In quest'ottica, come già accennato nel post del 18 Febbraio 2010, è spesso possibile integrare un Case Study all'interno di un White Paper, proprio perchè la descrizione di una soluzione, tipica di un WP, acquista particolare pregio quando viene rafforzata dalla testimonianza di una sua applicazione concreta in un contesto reale.

Scrivere un CS significa raccontare una storia di successo, raccontare come un prodotto si è integrato nella realtà di un cliente e ha risolto il suo problema. Questo consente uno stile realizzativo "più narrativo" rispetto al WP, più libero ma non per questo meno rigoroso.

Realizzare un CS implica NECESSARIAMENTE il coinvolgimento del cliente che ha adottato la soluzione.
Pubblicare il CS con il doppio logo, il vostro e quello del cliente, è un passaggio INELUDIBILE per la credibilità del CS medesimo. Inoltre il cliente deve contribuire con una testimonianza diretta della sua soddisfazione sul valore del vostro prodotto/soluzione.

L'estensione di un CS non è generalmente inferiore alle 2/3 pagine e non dovrebbe superare le 4/5 pagine.

Gli elementi chiave di un CS sono 5:
  • Il Cliente: presentazione della sua azienda, del settore in cui opera e di tutti i dati più rilevanti per inquadrare la sua posizione nel mercato.
  • Il Problema: presentazione dei bisogni del cliente e delle sue necessità più salienti.
  • La Soluzione: descrizione delle tecnologie, dei prodotti, delle risorse e delle best practices che avete integrato nella soluzione del problema del cliente.
  • I Benefìci: descrizione dei vantaggi tecnologici/organizzativi/economici ottenuti attraverso la soluzione adottata (con particolare enfasi sulla riduzione dei costi e sul miglioramento qualitativo dei servizi offerti, corredati da dati, grafici e tabelle).
  • Il Testimonial: la dichiarazione virgolettata del cliente che presenta il proprio punto di vista, la propria soddisfazione rispetto alla soluzione adottata, il rapporto di fiducia che si è instaurato con il fornitore della soluzione.
Nello sviluppo del CS deve emergere chiaramente il valore aggiunto implicato dalla soluzione adottata e la specificità della medesima, nonchè i differenziatori qualitativi che la vostra soluzione presenta rispetto a soluzioni analoghe. In altri termini, perché è stata scelta proprio la vostra azienda e come avete applicato i vostri prodotti e competenze nella soluzione del problema.

Il punto chiave è proprio questo: qualsiasi soluzione che risolve un generico problema comporta dei vantaggi rispetto alla situazione di partenza, ma solo una soluzione mirata e di particolare pregio, consegna nelle mani del cliente un grande vantaggio competitivo da spendere nel proprio mercato di riferimento.

Ed è questo l'aspetto che dovete far emergere, il "gancio concettuale" che vi permetterà di catturare l'attenzione del prossimo potenziale cliente.

La struttura standard del documento potrà seguire lo schema indicato di seguito:

- Titolo
- Sottotitolo (in una frase, indica il principale vantaggio per il cliente)
- Presentazione del cliente
- Descrizione del problema
- La soluzione
- I vantaggi che il cliente ha ottenuto
- La testimonianza diretta del cliente (una citazione, inserita tra virgolette)
- Eventuali sviluppi futuri della soluzione
- Tutti i contatti (mail, sito internet, telefono della vostra azienda)
- Nota di copyright e data di realizzazione

In un CS si racconta una "storia", attraverso un linguaggio preciso, sintetico, diretto, supportato se possibile da grafici e tabelle, cioè da dati significativi e facilmente interpretabili.

Bisogna raccontare bene "il prima della soluzione" e "il dopo la soluzione".

Essendo una "storia di successo" potete affidarvi al classico schema giornalistico delle 5 W (who, what, when, where, why).

Il doppio logo va messo SICURAMENTE sulla prima pagina (in alto, prima del Titolo) e sull'ultima pagina del CS (in basso dopo i contatti e la nota di copyright, "a chiudere" il CS). Se volete potete mettere il doppio logo su ogni pagina, ma a me sembra eccessivo.

Prossimamente  vi proporrò un template di riferimento.
Come sempre, non pretendo di esaurire l'argomento in poche righe e vi ricordo quello che vi ho decritto è solo uno schema generale, una mappa... MA LA MAPPA NON E' IL TERRITORIO... e lo schema può essere arricchito in base alle vostre esigenze, anche se vi sconsiglio di stravolgerlo.
Rimango in attesa di osservazioni, critiche e contributi.
Leggi questo articolo...

domenica 21 novembre 2010

Perchè un'azienda dovrebbe assumere un Technical Writer: seconda parte

Nel post precedente ho illustrato 5 ottimi motivi per i quali un'azienda dovrebbe avvalersi della professionalità di un TW. Ed ora, altri 5 motivi... vediamo se vi convinco!
;-)

6: Una buona documentazione parla della Qualità e dell'affidabilità di un'azienda

Quando compro un prodotto e la Quick Start Guide è incomprensibile, mi sento un cliente di serie B e probabilmente non comprerò un nuovo prodotto da quell'azienda, perchè mi comunica la sensazione di non aver cura dei suoi clienti. Forse è un'azienda solo motivata a massimizzare il proprio profitto, comprimendo anche i costi necessari a sviluppare la qualità del prodotto, probabilmente priva di una visione di medio-lungo periodo. E perchè dovrei fidarmi di un'azienda che non si proietta nel SUO futuro? Perchè IO dovrei credere in qualcuno che non crede in se stesso?
Una buona documentazione nobilita il brand di un'azienda ed è un moltiplicatore del rapporto di fiducia fra l'azienda e i suoi clienti.

7: La documentazione fornisce una "memoria" utile a chi sviluppa il prodotto.

Quando un prodotto è particolarmente potente e versatile, risulta inevitabilmente anche complesso da configurare e difficile da usare. Questo non dipende, in tal caso, dal fatto che sia stato progettato/disegnato male, ma deriva dalla sua ricchezza funzionale. L'evoluzione di un prodotto di questo tipo, prima ancora della sua commercializzazione, richiede lo sviluppo di una documentazione accurata, prima di tutto per uso interno, facilitando l'attività di sviluppo del prodotto medesimo.

Tipicamente, quando un nuovo membro viene inserito nel team di sviluppo, se dispone di un set di documenti adeguato può acquisire rapidamente il know-how necessario e risultare produttivo in un tempo molto breve.
Se invece deve essere continuamente affiancato da un supervisore più esperto e deve acquisire le competenze secondo lo schema "prova-sbaglia-impara-riprova", il suo inserimento sarà più lento ed inefficace.

Non siete convinti? Venerdì scorso il mio collega Riccardo ha chiesto di prendere in visione il manuale di un'applicazione Web sviluppata per un cliente, perchè deve realizzare le procedure di collaudo dell'applicazione medesima.

Grazie al fatto che il manuale è già pronto, Riccardo potrà realizzare un documento di collaudo preciso ed efficace molto velocemente.

8: Una documentazione accurata riduce i costi di supporto ed help-desk

Se un prodotto è ben documentato, i clienti possono trovare la maggiorparte delle risposte che necessitano all'interno della documentazione. Ovviamente questo non esime l'azienda che realizza quel prodotto a fornire supporto tecnico e servizi di help-desk. Ma tali servizi costano non poco e sono tanto più onerosi quante più ore di supporto devono fornire.
Se non siete convinti, vi invito a leggere questo post, datato 1995 ma ancora attuale, dal sito Web della AllBusiness.

9: Un Technical Writer può fornire supporto alla realizzazione di corsi d'aggiornamento

Dovendo documentare i prodotti/servizi/soluzioni/architetture di un'azienda, il TW finisce per divenire un esperto di tali argomenti. In particolare, è molto frequente che un tecnico conosca alla perfezione il prodotto di cui si occupa, ma magari non conosca altrettanto bene il prodotto sviluppato dal collega che lavora nella stanza accanto. Il TW  invece acquisisce una conoscenza a 360° della soluzioni aziendali. E' inoltre un esperto di comunicazione ed è abituato a guardare ognoi aspetto dal punto di vista del cliente.

Quindi è particolarmente in grado di sviluppare la documentazione e occuparsi della conduzione dei corsi d'istruzione che vengono erogati ai clienti.
 
10: Un Technical Writer possiede uno skill molto versatile

Il TW sa scrivere i documenti che accompagnano un prodotto, ma può essere coinvolto anche nella scrittura di altre tipologie di documenti, come i contratti o i documenti di offerta. Conosce tutti i prodotti aziendali, quindi può condurre corsi presso i clienti che hanno acquistato il prodotto. Ha conoscenze di grafica e di tecnologie Web (Html, Xml, CMS, Blog,...) e può contribuire alla gestione del sito Web aziendale e alla costruzione dei suoi contenuti. Aiuta il team tecnico a testare e collaudare un prodotto. Sa realizzare una presentazione e conoscendo i prodotti aziendali può affiancare l'attività di pre-vendita o diventare egli stesso un pre-seller.

Un TW può quindi essere utile in diverse zone della scacchiera, può giocare in diversi ruoli, può adattarsi alle esigenze dell'azienda.

---
Adesso avete 10 buone idee sulle quali ragionare.

Ricordatevi che qualsiasi cosa state realizzando, SEMPLICEMENTE NON ESISTE... se non c'è qualcuno che la va a raccontare in giro.

La comunicazione tecnica è solo un sottoinsieme della più ampia strategia di comunicazione, che include la pubblicità e il marketing, finalizzata a sostenere un prodotto. Potete scegliere di non investire nella comunicazione, ma in tal caso non potrete lamentarvi della pochezza dei vostri risultati.
Per la serie "Uomo avvisato...".

POST SCRIPTUM

Recentemente, ho sentito un ingenuo collega affermare che "... Oracle è un prodotto che si vende da solo...".
Nel 1982, quando avevo 16 anni e programmavo in assembler il mio Commodore 64, Oracle era poco più di una start-up, nata qualche anno prima dalle ceneri di un vecchio progetto commissionato dalla CIA e miseramente fallito. Fatevi i conti di quanto hanno investito negli ultimi 28 anni, in termini di pubblicità, marketing e documentazione tecnica, prima di arrivare ad essere "un prodotto che si vende da solo", autentico dominatore del mercato. Sono i migliori? Oggi credo di si, ma negli anni '80 certamente no!

Cosa ha fatto la differenza, cosa ha scavato un solco che oggi sembra difficile da colmare, come hanno moltiplicato i ricavi del loro business? E' solo merito dell'indubbia sagacia tecnica delle loro soluzioni? Fatevi una domanda... datevi una risposta... E NON PRENDETE SCORCIATOIE COME IL MIO INGENUO COLLEGA!
Leggi questo articolo...

sabato 20 novembre 2010

Perchè un'azienda dovrebbe assumere un Technical Writer: prima parte

Mi sono imbattuto in un interessante articolo di Ben Minson, che illustra diversi motivi per i quali un'azienda dovrebbe considerare conveniente l'apporto di un Technical writer e valutare l'opportunità di avvalersi dei suoi servizi.

Per chi volesse leggere l'originale in inglese, può andare su questo link.
Per tutti gli altri, vi propongo una sintesi tradotta e ragionata, conforme all'originale ma con qualche licenza personale, finalizzata a snellire, riorganizzare e contestualizzare le ottime indicazioni di Minson.

1: L'utente finale ha bisogno della documentazione

Sembrerebbe un motivo ovvio e banale, in grado già di giustificare l'apporto di un TW.
Alcuni utenti hanno bisogno di essere istruiti attraverso un corso, altri preferiscono imparare ad usare un prodotto semplicemente usandolo, secondo lo schema "prova-sbaglia-impara-riprova", altri si stanno abituando all'uso dei video-tutorial e privilegiano tale modalità.

Ma la maggiorparte necessitano sicuramente di una documentazione, in formato cartaceo e/o digitale, quanto più completa ed accurata, in grado di illustrare, al contrario degli approcci sopraindicati, TUTTI gli aspetti del prodotto.

Inoltre, più il prodotto è complesso e sofisticato, meno risultano efficaci gli approcci che prescindono da un set organico di documentazione dedicata.

Se parlate con i progettisti di un certo prodotto, vi diranno quasi sempre che la loro "creatura" è ben disegnata e facile da usare.

NON GLI DATE ASCOLTO! STANNO MENTENDO! Ma non perchè sono in malafede o perchè vogliono vendervi per forza la loro soluzione. Semplicemente perchè essendo utenti esperti e spesso poco inclini alla comunicazione, non sono in grado di valutare le difficoltà dell'utente finale nell'uso del prodotto.

Il lavoro del TW è proprio quello di rendere comprensibile e facile da usare ciò che può spesso risultare complicato, sia esso un prodotto/un processo/un'architettura.

2: La buona documentazione può evitare pericoli per la salute dell'utente finale

Sembrerebbe un'affermazione "forte", forse eccessiva. Ma immaginate un dispositivo elettro-meccanico non accompagnato da un'accurata documentazione relativa ai corretti livelli di tensione e di corrente per la sua installazione e il suo funzionamento. Oppure, per un medicinale importante, un foglietto informativo (tristemente noto come "il bugiardino") impreciso e/o incompleto. In questi casi la salute degli utenti è messa rischio e l'affermazione iniziale appare ben ponderata.

3: Documentare correttamente il prodotto è una tutèla anche per il produttore

Dall'uso scorretto di un prodotto possono derivare danni per l'utilizzatore. Se mi accingo ad utilizzare un elettrodomestico e nessuno mi avvisa che è pericoloso utilizzarlo con le mani bagnate, posso essere folgorato e potrei successivamente tentare di rivalermi sull'azienda che non mi ha fornito le giuste indicazioni. In generale, avvisare il cliente delle insidie che scaturiscono da un uso improprio di un prodotto rappresenta la linea di tutèla minima che qualsiasi azienda dovrebbe praticare onde evitare contenziosi legali indesiderati e pericolosi, sia in termini di immagine che in termini economici.

Anche in quest'ottica l'apporto di un TW può essere particolarmente incisivo.

4: La documentazione come volàno per la vendita del prodotto

Minson cita la testimonianza di Matt Asay, ex dirigente per lo sviluppo del business per Alfresco, uno dei Content Management System open source più "rampanti" degli ultimi tempi. Matt afferma: "Il 30% degli utenti che visitano il sito di Alfresco lo fanno per scaricare e prendere in visione la documentazione, per poter valutare le caratteristiche del prodotto. La documentazione è stata spesso vista come la "parente povera" dello sviluppo del software. Ma lo sviluppo di software senza documentazione è banalmente autoreferenziale. Un'azienda che sviluppa buona documentazione, mostra attenzione per i clienti e li induce a scaricare il software ed utilizzarlo, favorendone la diffusione".

Hanna Kirk sostiene: "Aiutando il cliente ad usare un prodotto con facilità, si aumenta la percezone della qualità del prodotto, quindi il suo successo".

5: Il Technical Writer può aiutare a migliorare il prodotto

L'ottica di chi sviluppa un prodotto è focalizzata sul rispetto delle specifiche, che vanno armonizzate con le tecnologie diponibili, e sul rispetto dei tempi di consegna prefissati. E' quindi improbabile che possa anche tener contro del "punto di vista" dell'utente che dovrà usare quel prodotto. Il TW è invece abituato a guardare il prodotto "con gli occhi del cliente".

Nella aziende più illuminate, il TW viene coinvolto nello sviluppo del prodotto e contribuisce a migliorarne le prestazioni DURANTE la fase di progettazione. La sua sensibilità nel cogliere difetti e limiti di una soluzione può anche risultare preziosa per risparmiare tempo e denaro, ottimizzando la fase di progettazione. In questo modo arricchisce "la consapevolezza" del team di sviluppo che quello che si sta progettando non è un oggetto autoreferenziale, ma lo si sta realizzando perchè lo dovrà usare qualcun'altro.
Inoltre, usando il prodotto per poterlo documentare, è il primo "cliente virtuale" in grado di tracciarne tutti i difetti del prima che venga immesso sul mercato.
Spesso riesce anche a cogliere comportamenti indesiderati di un prodotto, che emergono quando vengono realizzate delle sequenze operative inusuali, che i progettisti non avevano preso in considerazione.

Tutto ciò si traduce in un solo concetto: MIGLIORAMENTO DELLA QUALITA'DEL PRODOTTO.

Al prossimo post, per esplorare altri buoni motivi per assumere un Technical Writer...
;-)
Leggi questo articolo...

domenica 14 novembre 2010

E' in libreria "Comunicazione low cost" di Cristina Mariani

E' da poco disponibile nelle migliori librerie il nuovo libro di Cristina Mariani: "Comunicazione low cost".

Cristina è una brillante consulente di marketing, che ha da molti anni concentrato la sua attenzione su tecniche e strumenti di marketing e comunicazione a basso costo, rivolte in particolar modo alle piccole (a volte piccolissime) e medie imprese.

Nelle piccole realtà imprenditoriali spesso non si dispone di un budget tale da poter impiantare delle campagne di marketing "tradizionali". Ma oggi esistono moltissimi strumenti in grado di far conoscere la qualità di un'azienda e dei suoi prodotti a costi irrisori.

Nel libro c'è anche un mio breve intervento sull'argomento White Paper, uno degli strumenti di pre-vendita più potenti che si possano immaginare, ma che nella cultura della comunicazione d'impresa italiana non è ancora sufficentemente considerato.

Da Giovedì scorso è attivo il link per acquistare il libro sul sito della Franco Angeli.

Per chi volesse prendere in visione l'indice del libro, può farlo seguendo questo link.

Ovviamente vi invito anche a frequentare il suo blog, già presente nella sezione DA VISITARE di questa pagina.

Ringrazio ancora Cristina per la considerazione espressa nei miei confronti e spero che questa sua ultima fatica abbia ancor più successo del suo primo libro, "Marketing low cost", già molto apprezzato dai suoi lettori. Leggi questo articolo...

mercoledì 27 ottobre 2010

Ecco un blog interessante ed originale sulla comunicazione tecnica

Oggi vi segnalo il blog curato da Barbara Zen.

Barbara è un'esperta di grafica e illustratrice tecnica, talvolta impegnata anche nella redazione della documentazione tecnica dei prodotti di cui si occupa.

Nel sul blog vi potrete imbattere in diversi contenuti interessanti, idee e video spesso originali, curiosità e spunti quasi sempre incentrati sulla ricerca della Qualità da conferire al processo di comunicazione che deve guidare il cliente all'utilizzo dei prodotti. La cosa che più mi ha "intrigato" è proprio la sua attenzione ad un'ottica incentrata sui bisogni del cliente finale.

Questo approccio, che dovrebbe essere un "must" per il comunicatore tecnico, non sempre viene perseguito e praticato con la giusta energia. Spesso, ci ritroviamo a scrivere documenti strangolati nei limti di standard formali/legali o normative che provvedono ad ogni sorta di obiettivo meno che all'obiettivo principale, che dovrebbe essere l'efficacia del processo di comunicazione  prodotto/manuale/uomo.

Fra le altre cose, ho scoperto che abbiamo una comune passione per Robert M. Pirsig ed il suo immortale "Lo Zen e l'arte della manutenzione della motocicletta".

Non mi chiedete di cosa parla... leggetelo!

E visitate il blog di Barbara, sperando che vi piaccia come è piaciuto a me. Leggi questo articolo...

venerdì 22 ottobre 2010

Il mio PC ha fatto booommmm!

Ehhh si... si vede che lo stresso troppo. Uno dei famigerati update di Windows lo ha steso! Ora l'ho rimesso in piedi, ma con tutto il software che devo reinstallare, mi ci vorrà almeno tutto il week-end. E ancora non mi funziona il Wi-Fi. Sgrunt! Ma alcuni post sono quasi pronti, quindi non cambiate canale!
Azz... mi starò montando la testa?
:-) Leggi questo articolo...

sabato 16 ottobre 2010

Calcolare il valore degli Indici di Leggibilità con Word

Nel post del 10-10-2010 ho introdotto il tema degli Indici di Leggibilità.
La gran parte delle persone che scrive un testo sul PC usa Office Word.
Ma pochi sanno che Word offre la possibilità di valutare la leggibilità di un testo attraverso il calcolo degli indici Gulpease e Gunning Fog.

L'Indice Gulpease, presentato nel post sopraindicato, è adatto alla lingua italiana mentre il Gunning Fog è finalizzato alla lingua inglese (parole più corte e con poche sillabe).
 
Per poter eseguire il calcolo di tali indici, bisogna configurare Word con pochi semplici passaggi:

1.    Dalla barra dei Menù, selezionare Strumenti > Opzioni
2.    Nel pannello Opzioni, selezionare la scheda Ortografia e Grammatica
3.    Nella sezione Grammatica, spuntare la check-box Mostra le statistiche di leggibilità
4.    Premere il pulsante Ok, in basso a destra nel pannello Opzioni

A questo punto, se volete analizzare la leggibilità del vostro documento, dovete eseguire un controllo ortografico:

1.    Dalla barra dei Menù, selezionare Strumenti > Controlli Ortografia e Grammatica

Al termine del controllo ortografico viene visualizzato il pannello riassuntivo:

 
 I dati presenti nel pannello sono riferiti alle prime 3 frasi di questo post.

Leggi questo articolo...

lunedì 11 ottobre 2010

Buone prospettive per la professione di Technical Writer!

Ogni tanto una buona notizia ci vuole!

Dal blog di Luisa Carrada vi segnalo un post in cui si prospettano buone possibilità per la professione di Technical Writer, specialmente per coloro che padroneggiano la lingua inglese. La notizia si riferisce al mercato USA per il 2010, ma con le dovute pinze possiamo immaginare di poterla proiettare anche sul mercato nazionale ed Europeo.

Nel post Luisa cita anche il mio blog, bontà sua.

Ho la piacevole sensazione che forse si sta iniziando a capire l'importanza della comunicazione tecnica per sviluppare e creare valore aggiunto nella logica di business di un'azienda.

Nel mondo anglosassone questo concetto è già consolidato e in crescita, in Italia ci sono ancora praterie inesplorate a disposizione.

Se son rose... Leggi questo articolo...

domenica 10 ottobre 2010

La Qualità della documentazione tecnica: la Leggibilità

Quante volte, davanti ad un documento tecnico, avete avvertito la sgradevole sensazione che stavate leggendo qualcosa di poco comprensibile, anche se magari eravate degli esperti dell'argomento trattato?

Quante volte avete pensato che quel documento era poco "leggibile"?

Con il termine "leggibilità" intendiamo una particolare proprietà per cui un testo risulta comprensibile, facile da leggere. Tale proprietà può essere associata a qualsiasi testo scritto ed è influenzata sia da aspetti fisici che da aspetti linguistici.

La lettura di un testo sullo schermo di un PC risulta mediamente più lenta del 20-30% rispetto allo stesso testo scritto su carta. Anche la capacità di concentrazione di un lettore tende a ridursi più velocemente se legge un testo da una pagina Web piuttosto che da un libro tradizionale. Di conseguenza, l'utente Web legge di rado parola per parola, ma tende a "scannerizzare" la pagina alla ricerca di punti "sensibili" alla sua attenzione (titoli, elenchi, spaziature, immagini, ecc...) e saltando velocemente da una parte all'altra della pagina.

Queste osservazioni, dipendenti dal supporto "fisico" sul quale collochiamo il testo, hanno permesso di formulare specifiche regole di scrittura per il Web, che sono riassunte nelle diverse Guide di Stile che potete trovare in rete e sulle quali tornerò prossimamente con un post dedicato.

La leggibilità "linguistica" riguarda l'uso della lingua in tutte le sue componenti, dalla scelta dei termini e della sintassi impiegata all'articolazione dei contenuti.

Lo studioso americano Rudolf Flesch fu il primo a proporre un metodo "oggettivo" per misurare la leggibilità (Indice di Flesch, 1946).
La formula tiene conto della lunghezza media delle parole, misurate in sillabe, e della lunghezza media delle frasi, misurata in parole.
I principi basilari sono molto semplici:
  • una parola lunga è in genere usata meno di una breve;
  • una frase lunga è di solito sintatticamente più complessa di una breve.
La formula di Flesch, adattata alla lingua italiana da Roberto Vacca, è la seguente:

F = 206 - (0,6 * S) - P

ove:
  • 206 è una costante normalizzatrice, finalizzata a mantenere i valori della formula compresi fra 0 e 100;
  • 0,6 è una costante relativa alla lunghezza media delle parole italiane;
  • S è il numero di sillabe contenute in un campione di 100 parole;
  • P è il numero medio di parole per frase presenti in un campione di 100 parole.
Se F>60, il testo è MOLTO leggibile.

Se 50<60, il testo è di MEDIA leggibilità.

Se F<50, il testo è POCO leggibile.

Per calcolare la leggibilità con questo indice è necessario scegliere un campione adeguato alla lunghezza del testo stesso (tanto per semplificare, una sezione almeno pari al 10-15% del testo).
Terminata questa operazione, si dovranno contare le sillabe contenute nel campione e calcolare il numero medio di parole per frase.

Come vedete, non è un'operazione banale.
Esistono anche altri indici, oltre a questo.

Nel 1987 un gruppo di linguisti dell'Università La Sapienza di Roma si è riunita attorno a Tullio De Mauro per costituire il GULP, Gruppo Universitario Linguistico Pedagogico. In questi laboratori è nato l'Indice Gulpease.


La scala di leggibilità secondo questo indice va da 100 (leggibilità massima) a 0 (leggibilità nulla). I lettori che hanno un'istruzione elementare leggono facilmente i testi che presentano un indice superiore a 80. I lettori che hanno un'istruzione media leggono facilmente i testi con indice superiore a 60. I lettori che hanno un'istruzione superiore leggono facilmente i testi con indice superiore a 40.
 

Quindi, per ottenere testi leggibili, bisogna semplificare!

La formula dell'Indice Gulpease è:

G= 89 - (Lp / 10) + (3 × Fr)

ove:

  • Lp = (100 × totale lettere) / totale parole
  • Fr = (100 × totale frasi) / totale parole
L'Indice Gulpease è il primo indice di leggibilità tarato sulla lingua italiana e ha il vantaggio di calcolare la lunghezza delle parole in lettere, anziché in sillabe. In rete è possibile trovare dei siti Web che consentono il calcolo dell'indice Gulpease e io ve ne propongo tre:

ANALIZZATORE LEGGIBILITA' 1 


ANALIZZATORE LEGGIBILITA' 2 


ANALIZZATORE LEGGIBILITA' 3

Sperimentateli.

Generalmente non siamo abituati a calcolare l'Indice di Leggibilità di quello che scriviamo.
Ma realizzare documenti leggibili può essere molto desiderabile quando scriviamo per il Web o quando dobbiamo valutare i costi da sostenere per tradurre i nostri documenti o quando scriviamo documenti per la Pubblica Amministrazione che poi devono essere proposti agli utenti.

Tali indici sono delle armi molto utili nella lotta al "burocratese" che, soprattutto in Italia, è spesso molto diffuso. Non è certo banale semplificare testi che trattano argomenti/concetti complessi, qualche volta è quasi impossibile. 


A maggior ragione, se ci riusciamo, possiamo dire di aver aggiunto un pezzo al puzzle della Qualità di un documento tecnico che tentiamo di costruire.

Leggi questo articolo...

giovedì 7 ottobre 2010

Come realizzare un Video Tutorial: i fondamentali

Per realizzare un Video Tutorial bisogna dotarsi di un software in grado di manipolare un filmato, magari realizzato con una videocamera o una web-cam, e che possa catturare le immagini che fluiscono sullo schermo di un PC. Ai fini della realizzazione di un Video Tutorial, sono veramente fondamentali poche funzionalità ed essenzialmente:
  • la possibilità di realizzare un filmato in diversi formati;
  • la possibilità di partizionare lo schermo in diverse zone;
  • la possibilità di avere funzionalità di "post-produzione", come quella di aggiungere la voce narrante dopo aver realizzato il video (rendendo asincrona la realizzazione dell'audio rispetto al video) o aggiungere testi scritti ed elementi grafici al video
 Io conosco direttamente due prodotti:
  • CamStudio
  • Camtasia Studio

CamStudio è un prodotto Open Source, gratuito, molto spartano ma efficace e la sua installazione dura circa un minuto. Consente di registrare qualsiasi attività che si svolge sullo schermo del vostro computer, prendendolo in considerazione nella sua interezza o selezionandone solo una regione specifica.
Il video prodotto è in formato AVI o SWF (formato Flash).
CamStudio consente inoltre di catturare l'audio dal microfono o dalle periferiche audio del sistema, nonchè di personalizzare il video con testo e note. L'interfaccia di CamStudio offre un menù essenziale ed intuitivo.
Se siete dei noefiti e non avete pretese iper-professionali, va benissimo.

CamtasiaStudio è un prodotto molto professionale, con licenza a pagamento, che fornisce numerose possibilità di configurazione. Produce filmati in diversi formati, oltre al formato proprietario CAMREC:
  • Flash (SWF/FLV) - Adobe Flash output
  • WMV - Windows Media streaming video
  • MOV - QuickTime movie
  • AVI video
  • iPod/iTunes
  • RM - Real Media streaming media
  • CAMV - Camtasia for RealPlayer streaming media 
  • GIF animation file
Anche Camtasia Studio consente di realizzare un video che registra tutto ciò che accade sull'intero schermo o solo in una parte di esso. Una volta terminata la registrazione si dispone di un ampio insieme di opzioni di post-produzione (diverse modalità di editing, effetti di transizione, aggiunta del commento audio, zoom, definizione di rapporti di compressione del video, aggiunta di un watermark,...).

Prendere confidenza con questi strumenti è un pre-requisito per poter iniziare a sviluppare un Video Tutorial.
Come ripeto, ce ne sono molti altri, sia freeware (gratuiti) che a pagamento.

Dovete valutare quello che vi interessa in base alle vostre esigenze e poi potete iniziare a "giocare". A presto.
Leggi questo articolo...

lunedì 4 ottobre 2010

Un esempio di White Paper tecnico

Nel mese di Aprile vi avevo illustrato una classificazione dei diversi tipi di White Paper che si potevano realizzare. Tra questi, avevo indicato quali erano le caratteristiche fondamentali di un White Paper "tecnico".
Ora ecco un un esempio classico di questa tipologia. Potete confrontare la struttura di questo WP della Symantec con le linee guida che vi avevo fornito nel post del 25 Aprile e rilevare una sostanziale sovrapposizione delle due impostazioni... oppure no?!? Si accettano eventuali contestazioni! :-) Leggi questo articolo...

sabato 2 ottobre 2010

Il Video Tutorial: uno strumento efficace per una comunicazione agile

Da quando YouTube ha sdoganato il film-maker che c'è in ognuno di noi, il "video" è uscito dal recinto della produzione artistica ed è diventato, grazie anche alla diffusione di strumenti di riproduzione hardware/software a basso costo, un mezzo di  comunicazione che tutti possono utilizzare in qualsiasi frangente, allo scopo di documentare le proprie attività, passioni e i diversi momenti di vita di ognuno di noi.

Ma da qualche anno, nell'ambito della comunicazione tecnica, si è diffuso l'uso del Video-Tutorial, un particolare tipo di video in cui vengono descritte delle sequenze operative ben definite inerenti all'uso di applicazioni software, strumenti tecnici e soluzioni tecnologiche di vario tipo.

Il Video Tutorial è una nuova frontiera per il comunicatore tecnico ed è uno strumento complementare rispetto al panorama delle diverse opzioni tradizionali.

Ricordiamo che un Tutorial è un documento in cui un certo argomento viene esposto in una modalità estremamente semplificata,  attraverso delle descrizioni sintetiche, spesso in modalità "passo-passo", corredate da immagini di supporto finalizzate a migliorarne la comprensione.

Un Video Tutorial si ispira allo stesso schema, ma sfrutta il connubio tra immagini e parole per rendere ancora più incisiva ed  immediata l'efficacia comunicativa.

Una caratteristica specifica del Video Tutorial è quella della brevità.

Mentre un Tutorial tradizionale cartaceo può comunque essere un documento anche molto voluminoso, un VT deve avere uno sviluppo che può ragionevolmente oscillare tra i 3-4 e i 15-20 minuti. Ovviamente nessuno vi impedisce di realizzarne uno da 2 ore, ma non credo che potrà riscuotere particolari consensi, indipendentemente dall'argomento e dalle vostre capacità didattiche.

In rete vi sono numerosissimi esempi di VT, non sempre di qualità eccelsa, ma comunque interessanti.

Per iniziare, segnalo questo sito agli appassionati di grafica e in particolare di Photoshop, dove troverete numerosi VT in italiano sull'uso del più famoso software di fotoritocco.

Invece, per gli appassionati di altri prodotti Adobe, vi segnalo la Web TV di Adobe, in cui sono illustrate le diverse funzionalità dei vari moduli della suite.

E PRECISO CHE NON PRENDO SOLDI DA ADOBE! :-)

E per uscire dal campo ICT, un omaggio alle frequentatrici del blog con un make-up VT tanto per tenere sempre a mente l'altra metà del cielo!
Leggi questo articolo...

sabato 25 settembre 2010

Le immagini in un documento sono importanti: meglio se belle e free!

Vi ho già proposto in passato alcuni post relativi all'importanza dell'uso di immagini, grafici e tabelle in un documento tecnico. In questi giorni su Linkedin ho seguito una discussione in cui diversi technical writer hanno ammesso la loro inadeguatezza nel campo della realizzazione di immagini efficaci da inserire nei loro documenti. Di contro, è quanto mai raro che un'azienda, specialmente nel campo ICT, decida di pagare un grafico professionista a supporto dell'attività di comunicazione tecnica e di marketing.
Di conseguenza, i TW sono chiamati ad arricchire il loro skill per poter realizzare autonomamente gli add-on grafici di cui hanno bisogno. Io non sono un grafico e mi ritrovo spesso a dover provvedere in prima persona a realizzare gli elementi grafici che inserisco nei miei documenti, ottenendo risultati credo (spero...) assolutamente soddisfacenti ma certo non paragonabili a quelli che potrebbero essere ottenuti da un vero grafico.

In quest'ottica vi segnalo un post dal blog di Giacomo Mason (già presente nella sezione DA VISITARE), in cui l'autore mette a fuoco la valenza dell'uso delle immagini in una presentazione e fornisce un set di link utili per accedere ad immagini gratuite e copyright-free.

Sapere di poter attingere a delle collezioni di belle immagini già pronte è consolante, specie per chi conosce la fatica dell'autodidatta e le annesse nottate passate su Photoshop a filtrare, sovrapporre, provare effetti e ancora e ancora... tutto per beccare l'immagine "giusta". Leggi questo articolo...

venerdì 24 settembre 2010

La documentazione tecnica come moltiplicatore di business revenues

Vi segnalo un articolo pubblicato su Forbes da Aron Fulkerson, in cui l'autore sostiene che, per un'azienda "illuminata", lo sviluppo della documentazione di prodotto può essere un moltiplicatore economico assolutamente non banale, sia in termini di abbattimento dei costi di supporto ed help-desk, sia per ciò che riguarda la fidelizzazione del cliente e la promozione del proprio business (se avete tempo e voglia potete andare a rivedere i miei articoli inerenti all'argomento White Paper).
Aron Fulkerson è co-fondatore e CEO di  MindTouch.
In passato ha  lavorato per Microsoft e nell'ambito della ricerca sui sistemi distribuiti.

Leggi questo articolo...

domenica 19 settembre 2010

La Qualità non è un pranzo di gala.

Mentre pensavo al titolo di questo post, mi è venuta in mente una delle più famose frasi di Mao Zedong e con un eccesso di immodesta imprudenza ho pensato che, sostituendo la "Qualità" alla "Rivoluzione", facesse proprio al caso mio

Nell'ultimo post vi ho parlato di due attributi, la Chiarezza e la Sintesi, che contribuiscono a definire la Qualità di un documento tecnico.

Ma il percorso che ci porta a dare sostanza a queste due caratteristiche non è un regalo degli Dei, non nasce dallo sfolgorio scintillante del talento (per lo meno non nel mio caso) o da una qualche formuletta magica, ma è frutto di un lavoro "muscolare", faticoso, in cui il testo deve essere lavorato, asciugato, riletto e riscritto, a volte scompaginato e riorganizzato, corretto e limato attraverso un processo iterativo che assomiglia al lavoro dello scultore, che toglie dal blocco di marmo tutto l'inessenziale per far emergere quello che già esiste "nel marmo", affinando via via il lavoro del martello e dello scalpello.

Sull'argomento della revisione di un testo ho già scritto diversi post, riuniti nella sezione Esercizi di riscrittura.

In particolare vi invito a leggere i post del:

Quello che mi preme sottolineare è che:
  • la ricerca della Qualità è un PROCESSO e come tale può essere studiato e ingegnerizzato;
  • la Qualità non è mai gratis, ma richiede un lavoro;
  • la Qualità è un "TUTTO" che molto spesso non riusciamo ad ottenere completamente ma a volte, con opportune strategie, possiamo ottenere almeno "UNA PARTE DEL TUTTO" e sarà comunque meglio del "NULLA".
Leggi questo articolo...

giovedì 16 settembre 2010

La Qualità della documentazione tecnica: Chiarezza e Sintesi

Iniziamo questo percorso alla ricerca della Qualità della documentazione tecnica, secondo uno schema ispirato al principio del "learning by doing", partendo da osservazioni concrete e cercando di desumere, da queste, dei principi di ordine generale... se possibile!

Quando decidiamo di leggere un romanzo per passione e per diletto, è spesso molto gratificante abbandonarsi nei labirinti concettuali che l'autore ci propone, seguendo il filo di una costruzione intrigante e ricca di enigmi e sorprese.

Quando invece leggiamo un documento tecnico, lo facciamo per motivi professionali.
Cerchiamo in esso informazioni che ci servono per il nostro lavoro, per risolvere problemi concreti (installare un software, montare un armadio, configurare le funzionalità del nostro nuovo televisore al plasma,...), disponendo di tempi generalmente sempre molto compressi.

Quindi cosa c'è di più desiderabile di un documento incentrato sulla CHIAREZZA e sulla SINTESI?

In effetti è proprio quello che vogliamo: trovare tutte le informazioni che ci necessitano espresse chiaramente, senza omissioni e senza inutili giri di parole. C'è qualcuno di voi che ha il coraggio di alzare la mano e contestrmi? Chi di voi vuole leggere un documento OSCURO e PROLISSO? Quindi sto sostenendo un'ovvietà! Siete proprio sicuri?

Ora mi viene in mente che avrei potuto scivere "senza inutili circonlocuzioni".
Secondo me "CIRCONLOCUZIONI" è molto meno di chiaro di "GIRI DI PAROLE".
Però è più sintetico, è una sola parola, mentre "GIRI DI PAROLE" sono 3 parole!

Il problema è proprio questo: generalmente CHIAREZZA e SINTESI sono due proprietà in contrasto.
UN esempio? Eccolo:

FRASE 1
"MyNet Manager è un prodotto finalizzato alla gestione ottimizzata di una LAN (Local Area Network). Attraverso la Web COnsole di Amministrazione di MyNet Manager, è possibile configurare facilmente numerosi parametri per l'analisi e la gestione della vostra rete. MyNet Manager vi mette a disposizione un largo set di opzioni finalizzate ad individuare e tracciare tutte le informazioni che caratterizzano la dinamica funzionale della vostra rete"

E' chiaro? Non ne sono certo. E' sintetico? No!
Che cosa avete capito? Troppi aggettivi? Temo di si.
Riscriviamolo:

FRASE 2
"MyNet Manager è una Administration Web Console che vi permette di monitorare un largo set di caratteristiche della vostra LAN (Local Area Network), configurando facilmente un gran numero di parametri necessari a tale scopo".

Questa versione mi piace, mi sembra abbastanza chiara e più sintetica.
La volete più sintetica?

FRASE 3
"MyNet Manager vi permette di monitorare un largo set di caratteristiche della vostra rete locale".

Mi sembra ancora sufficentemente chiara e super sintetica.
Più di così non è possibile... o si?

FRASE 4
"MyNet Manager controlla la rete locale".
La rete di che? Di chi? In che senso la controlla? Come?
No, qui non ci siamo, abbiamo ottenuto una sintesi esagerata ma la chiarezza è scomparsa.

Se volessimo avere una rappresentazione grafica qualitativa della relazione che lega CHIAREZZA e SINTESI, potremmo disegnare un grafico di questo tipo:


Ad ogni FRASE k corrisponde una coppia di coordinate (SFk,CFk) che corrispondono ai valori di SINTESI e CHIAREZZA della frase in esame.
Come si osserva facilmente, quando la sintesi è elevata (SF4), la chiarezza tende a 0 (CF4). Se la sintesi invece tende a 0 (SF1), la chiarezza tende ad essere più elevata (CF1).
Esiste poi una coppia di valori (SF,CF), indicata in BLU
, che ci consente di massimizzare la chiarezza, accettando un livello di sintesi non troppo elevato. Aumentando il valore della sintesi si arriva ad individuare una zona del grafico caratterizzata da un rettangolo azzurro che forse rappresenta la zona di miglior equilibrio tra i valori combinati di questi attributi.

In effetti, sia la FRASE 2 (SF2,CF2) che la FRASE 3 (SF3,CF3) possono essere considerate accettabili. Il grafico ovviamente è solo un modo di visualizzare l'andamento qualitativo che lega questi due concetti, un ausilio a supporto della mia tesi. La cosa che mi interssa veramente è sottolineare che CHIAREZZA e SINTESI sono ingredienti necessari e contrastanti, che devono essere armonizzati quanto più possibile e che possono rappresentare la prima tessera del puzzle della Qualità che stiamo tentando di ricostruire.
Leggi questo articolo...

martedì 7 settembre 2010

Lo Zen e la Qualità della documentazione tecnica

Quando avevo 17 anni ho letto "Lo Zen e l'arte della manutenzione della motocicletta" di Robert Pirsig, un libro che ritengo straordinario per molti versi e nel quale, per la prima volta, mi sono imbattuto in un'analisi sistematica del concetto di "Qualità".

“Il Buddha, il Divino, dimora nel circuito di un calcolatore o negli ingranaggi del cambio di una moto con lo stesso agio che in cima a una montagna o nei petali di un fiore”

Questa frase del libro è come una porta mistica, che trascina il lettore in un percorso complesso in cui Pirsig, ad esempio, si focalizza sulla struttura della filettatura di una vite.

La capacità di capire il senso e lo scopo della filettatura di una vite è la "chiave" che ci apre la porta per incontrare il concetto di Qualità. O meglio, è una delle innumerevoli facce con cui la Qualità/il Divino "ci parla".

In questi ultimi anni mi sono spesso ritrovato ad osservare che valutare la Qualità del proprio lavoro è un rompicapo poco circoscrivibile, perchè sono molti gli elementi da valutare e le relazioni che li legano.

Ma la domanda rimane e ne richiama un'altra, più prosaica, ma strategica: quanto costa un documento tecnico?

Di solito siamo abituati a pensare che il prezzo di un bene dipenda da alcuni fattori. Nel caso di un documento tecnico i 3 principali elementi sono:

- la qualità del documento
- il tempo impiegato a realizzarlo
- gli standard di mercato (cioè il generale rapporto tra domanda e offerta)

Questi 3 elementi principali sono spesso molto intrecciati (difficilmente si potrà chiedere un prezzo molto più elevato del prezzo medio di mercato per un certo documento, ad esempio un Tutorial, anche se avete implementato delle soluzioni qualitativamente molto pregiate, impiegando magari per questo motivo un tempo superiore alla norma).

Tuttavia, alla base c'è un impianto concettuale che non può prescindere dalla Qualità. Del resto, a Natale, ho spesso acceso il camino con delle Installation Guide che non hanno mai installato nulla!

Pirsig sarebbe capace di descrivere la Qualità di un documento tecnico secondo uno schema completo e sferico. Ma io non sono Pirsig e vorrei solo provare ad individuare alcune possibili ragionevoli risposte, basate sulla mia esperienza e su quella di altri TW.

Se volete contribuire, fatevi avanti.
Leggi questo articolo...

sabato 4 settembre 2010

Gli 8 errori da evitare in un White Paper: seconda parte

Nel post del 2-9-2010 ho indicato i primi 4 errori da evitare nella realizzazione di un White Paper. Ora analizziamo gli ultimi 4 errori.


ERRORE n° 5: contenuti non interessanti!

Carenza di dati validi e credibili, informazioni datate, link verso risorse non più raggiungibili,statistiche e informazioni non verificabili, impaginazione poco accurata, inutile spazio vuoto usato solo per allungare il numero delle pagine e altri orrori similari: tutto ciò svuota di credibilità il vostro White Paper.

Usate i dati (statistiche, case studies, industry report,…) di terze parti credibili e/o analisti riconosciuti del settore specifico di cui si occupa il WP.

Ma sappiate anche posizionare tali informazioni nel punto giusto e principalmente:

- nell’introduzione;
- in grafici e tabelle posizionate in prossimità dei concetti chiave;
- nelle note eventualmente presenti.

Scrivete in maniera chiara e semplice, utilizzando esempi efficaci e sintetici, con tabelle e grafici ben costruiti, fornendo riferimenti verificabili e autorevoli, costruendo il documento con ritmo ed incisività facendo emergere tutti i concetti chiave in maniera efficace.
Altrimenti, perché qualcuno dovrebbe leggerlo?


ERRORE n° 6: non utilizzare una struttura chiara!

La struttura classica di un White Paper può essere schematizzata nel modo seguente:

- SOMMARIO (1 pagina)
- INTRODUZIONE (1 pagina)

- DEFINIZIONE DEL PROBLEMA (2 pagine)

- ILLUSTRAZIONE DELLA SOLUZIONE (2 pagine)
- CASE STUDY (opzionale, 1 pagina)

- CONCLUSIONI (1 pagina)


Io prediligo uno schema un po’ meno spartano, più articolato, che vi ho già illustrato nel post del 18-2-2010, ma entrambi gli schemi possono essere validi, eventualmente con qualche opportuno adattamento.

Ma è importante che il lettore venga condotto per mano lungo un percorso logico e fluido, dall’introduzione, alla definizione del problema, all’illustrazione della soluzione, alle conclusioni.


ERRORE n° 7: un White Paper troppo corto non funziona!

Si stanno diffondendo WP di 2-4 pagine o addirittura degli “instant WP” di una sola pagina!

Un WP eccessivamente breve, nella infantile illusione di “farsi leggere” da decision maker con poco tempo ed attenzione, viene meno alla sua funzione didattico/educativa fondamentale che consiste nell’informare il lettore sulla soluzione di un problema.

Un WP troppo corto ricade, in un certo senso, nella tipologia dell’ERRORE n° 1, finendo per somigliare ad una Brochure o ad un Abstract.

Su questo aspetto vi segnalo l'opinione di Jonathan Kantor, un “White Paper Guru” molto autorevole.


ERRORE n° 8: sbagliare la chiusura!

Come abbiamo detto, al termine del White Paper il lettore deve avere voglia di contattarvi perché si è convinto che voi potete risolvere il suoproblema. Quindi dovete fornirgli tutti i necessari riferimenti, magari avendo cura di evidenziarli graficamente.

Nella mia esperienza, non sempre il White Paper presenta una chiusura ben organizzata.
Ecco un esempio della “struttura tipo” di una pagina di chiusura, in cui ho volutamente enfatizzato con colori molto marcati le diverse parti che la compongono:


Francamente vi sconsiglio caldamente di utilizzare dei colori così dissonanti in un caso “reale”!

L’importante è focalizzare che nella pagina di chiusura si devono riassumere i vantaggi della soluzione proposta (riquadro verde, in alto a sx), sottolineando eventualmente i passaggi chiave per ottenerla (riquadro beige, in basso a sx).

In alto a dx il logo aziendale o un’altra immagine efficace e in basso a dx tutti i riferimenti per contattare l’azienda. Ovviamente non è l’unica struttura possibile, è solo un esempio, ma è un buon punto di partenza.

Se il vostro White Paper non è contaminato da questi 8 errori, è probabile che sia un buon documento!
Leggi questo articolo...

giovedì 2 settembre 2010

Gli 8 errori da evitare in un White Paper: prima parte

In numerosi post precedenti ho cercato di raccontarvi “che cos’è un White Paper”.

In estrema sintesi, un White Paper è un documento di lunghezza variabile tra le 8 e le 15-20 pagine il cui scopo è quello di informare e convincere il lettore attraverso l’identificazione accurata di un problema e la conseguente illustrazione della soluzione che lo risolve.

Il White Paper “perfetto” deve indurre il lettore a contattare l’azienda che attraverso questo documento ha illustrato la sua soluzione.

In tal senso, un White Paper può essere un documento fondamentale come supporto alla vendita di un prodotto, quindi si colloca in una “terra di mezzo” tra l’ottica tecnica e l’ottica commerciale.

Le statistiche disponibili (qui potete consultare un articolo ed un PDF, entrambi autorevoli), indicano che almeno 7 utenti su 10, ritengono che un WP sia:

- un ottimo strumento per conoscere le soluzioni di un’azienda;
- utile per investigare nuove soluzioni tecniche;
- molto influente nelle loro scelte finali.

Il lettore di questo tipo di documenti è generalmente un decision maker, nel senso più ampio del termine, che dispone di poco tempo e di un livello di attenzione non elevato e che evita istintivamente la lettura di documenti molto voluminosi, sempre alla ricerca di contenuti innovativi e interessanti, confezionati in una forma sintetica e incisiva.

Vi ho già parlato di COME DEVE ESSERE REALIZZATO un White Paper.

Ora ribaltiamo il punto di vista ed esaminiamo QUALI ERRORI FONDAMENTALI BISOGNA EVITARE!


ERRORE n° 1: il White Paper… è un White Paper, non altro!

Il White Paper NON E’ una Brochure, che ha il compito di “agganciare” l’attenzione di un potenziale cliente attraverso un flusso di comunicazione rapido, d’impatto e, in qualche modo, più “emozionale” che informativo.

Il White Paper NON E’ un Manuale Tecnico e non dispone di un gran numero di pagine (15 sono già molte) , quindi non deve entrare nei particolari di una soluzione né può indagare ogni aspetto tecnico di un prodotto.

Il White Paper NON E’ un Abstract in cui si riassume, in una sola pagina e in una forma esclusivamente testuale, il senso della soluzione proposta.

Il White Paper NON E’ una presentazione, in cui le informazioni vengono presentate in un formato estremamente asciutto e che richiede sempre il supporto della “voce narrante” per poter sviluppare i contenuti riassunti nelle diverse schermate.

Concludendo, il White Paper non è null’altro che un White Paper!

Se non avete chiara la distinzione fra la struttura ed il ruolo di un White Paper rispetto alla struttura ed il ruolo di altri tipi di documenti, il White Paper non risulterà credibile.


ERRORE n° 2: non saper individuare il vostro “lettore target”!

Dovete sempre chiedervi: chi leggerà il mio White Paper?

In altri termini, dovete essere in grado di saper rispondere a domande del tipo:

- Quale sarà il suo livello di conoscenza dell’argomento trattato?
- La sua posizione professionale?
- Che tipo decisioni può prendere?
- Quanto tempo/attenzione dedicherà alla lettura del mio White Paper?
- E’ più incline a leggere un documento stampato o in formato digitale?
- Quale tono sarà più proficuo (accademico, informale, tecnico, commerciale,…)?


ERRORE n° 3: sbagliare il titolo!

Sbagliare il titolo può essere un errore senza ritorno!

Lo spazio e l’attenzione che dedicherete ad un titolo potrà fare la differenza tra un decision maker che apre il vostro WP e lo legge oppure lo accantona a prendere polvere in un angolo della scrivania!

Alcuni trucchi? Almeno 2.

TITOLO E SOTTOTITOLO

Il titolo non dovrebbe svilupparsi con più di 8-10 parole.
Il sottotitolo può svilupparsi su 2/3 righe e può aiutare a fornire più elementi semantici a supporto del titolo, consentendo di realizzare una struttura “a due livelli” che presenta una maggiore e più efficace articolazione.

DITE AL LETTORE CHE COSA OTTERRA’

Se fin dal titolo riesco ad intuire la soluzione al mio problema, allora lo leggerò!

Un esempio?

Immaginate di aver bisogno di una piattaforma di Content Management System per la vostra azienda.
Vi sottopongono due WP, intitolati rispettivamente:

(WP 1) Una piattaforma completa e potente per la gestione della comunicazione aziendale

(WP 2) Gestione documentale, blog, forum e newsletter: poco tempo e pochi click per “esistere”

Io leggerei per primo WP2, e voi?

Il titolo di WP1 è generico e banale. Potrei mai desiderare una soluzione che non fosse “completa e potente”? O pensano che io sia così fesso da spendere soldi per una soluzione “debole e incompleta”? E che significa “comunicazione aziendale”? Ci sono molti tipi di comunicazione aziendale: la comunicazione di marketing, quella interna, quella specificatamente tecnica, quella istituzionale,… di che stiamo parlando?

Il titolo di WP2 invece funziona!
Mi dice subito che otterrò 4 cose concrete, in poco tempo e con pochi click, suggerendo una facilità d’uso sopra la media, attraverso le quali l’azienda sarà in grado di mostrarsi e di comunicare, quindi di “esistere”.

Il difetto di WP2 è che è troppo lungo.
Potremmo ristrutturarlo così:

TITOLO: Gestione documentale, blog, forum e newsletter… e l’azienda ESISTE!
SOTTOTITOLO: In poco tempo e pochi click è possibile configurare tutti gli strumenti fondamentali per gestire la documentazione e la comunicazione aziendale in modo integrato e flessibile.

Si può fare di meglio? Sempre… ma già così non è male.


ERRORE n° 4: il vostro lettore non conosce la soluzione che gli state presentando!

Assumere che il lettore sia un esperto dell’argomento trattato è un’ipotesi consolante, perché ci illude di poter lavorare di meno. Ma se fosse un esperto della soluzione che state proponendo, perché dovrebbe leggere il vostro White Paper? Bisogna evitare di eccedere nell’uso di acronimi, abbreviazioni gergali, terminologia eccessivamente tecnica , altrimenti il lettore si sente “respinto”.
Voi non siete più intelligenti perché siete dei super-esperti e lui non è un cretino perché non ha confidenza con lo specifico oggetto che state illustrando.
Il vostro lettore è un potenziale cliente, non dimenticatelo.

Il resto, nel prossimo post.
Leggi questo articolo...

mercoledì 25 agosto 2010

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