giovedì 31 dicembre 2009

Ultimo post dell'anno 2009: un primo bilancio


L’ultimo post del 2009 lo dedico ad un bilancio del primo anno di blog
.

L’idea è nata il 1° Gennaio 2009; non avevo mai gestito un blog ed ero molto curioso, invogliato anche dall’esperienza di mia moglie che aveva invece già aperto il suo, Puntodivistaceliaco.

Nei ritagli di tempo, dopo cena, i primi test, le scelte grafiche e i primi post.
Poco più di un mese di gestazione, tutto in linea dal 15 Febbraio e si parte!
Al 31 Dicembre il bilancio è positivo, ben aldilà delle mie aspettative.

Ma non mi riferisco solo agli aspetti statistico/numerici, che sono sintetizzati in fondo a questo post, bensì ad altri aspetti, che costituiscono “il motore” che poi genera certi numeri.

Avevo iniziato con alcune motivazioni molto chiare ed altre, invece, già molto dense ma indefinite, che hanno preso forma e senso a poco a poco.

Il blog come palestra di scrittura e comunicazione; il blog come cartina di tornasole, per vedere se la tua professione può interessare qualcuno e se quello che proponi può essere utile a qualcuno; il blog come esercizio didattico, per verificare se sei capace di spiegare efficacemente ad altri quello che hai imparato (o che presumi di aver imparato...) sulla tua pelle; il blog come luogo di confronto con professionisti del settore, magari molto più esperti di te; il blog come stimolo per approfondire aspetti del mio lavoro che spesso vengono indagati per il tempo strettamente necessario a produrre un risultato, perché il tempo, si sa, non basta mai.

Ma poi anche altro…

Il blog diventa il luogo dove le cose che hai scritto rimangono, ed allora se un collega ha bisogno di quella tale informazione, sulla quale hai scritto un post, gli dai il link e così non devi stare lì a rispiegare il medesimo concetto N volte ad N persone diverse.

E' anche un indirizzario, via via sempre più ricco, di tutte le risorse web in cui ho trovato elementi utili per il mio lavoro.

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.

Un esempio? Sto iniziando a riscoprire le regole grammaticali… io che ho sempre scritto “ad orecchio” e che a scuola preferivo un complicato problema di Fisica o di Matematica all’analisi grammaticale di una frase di 4 righe!

Il blog talvolta anche come testimonianza di scelte politiche sulla libertà della rete, argomento molto delicato e forse non ancora presente nella consapevolezza di tutti noi.

E altro che forse ancora non ho messo bene a fuoco, ma che “so che c’è”.

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


Prima un inizo timido, poi un sensibile e prolungato incremento di contatti e infine una “normalizzazione” forse fisiologica; tuttavia, mai “andamento piatto”, per fortuna!

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.000 visitatori; di questi, circa 3.500 ritornano abitualmente sul blog
Il tempo medio di visita si aggira intorno ai 3 minuti, per tutti i 13.000 visitatori.
I nuovi visitatori indugiano per circa 1’40”, quelli che ritornano lo navigano per circa 6’40” .
Le pagine visitate sono circa 25.000 ma se eliminiamo almeno il 20% di pagine che vengono accedute “per caso” e poi subito abbandonate, diciamo che scendiamo a circa 20.000.

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


Del resto, per un blog scritto in italiano, che si occupa di una professione di nicchia, non potevo certo aspettarmi qualcosa di diverso.

Quando ho iniziato il blog, se mi avessero detto che avrei ottenuto la metà di questi numeri, avrei messo la firma. Ma come ripeto, i numeri sono solo un elemento di curiosità e non spiegano necessariamente tutto, anche se aiutano a capire anche in che modo poter migliorare i contenuti e la struttura del blog.

Possiamo chiudere qui.
Ci vediamo domani, nel 2010, un anno in cui spero che l’ottimismo della volontà possa prevalere sul pessimismo della ragione.
Vi auguro uno splendido 2010, pieno di salute, lavoro e serenità, che sono le cose più importanti.
Ciao. Leggi questo articolo...

sabato 26 dicembre 2009

Il blog di Henry Miller

Oggi vi segnalo un nuova risorsa, che ho aggiunto alla sezione DA VISITARE.
E' il blog di Henry Miller, un TW che sta esplorando da molto tempo le possibilità espressive dei video-tutorial, una frontiera molto efficace in alcune aree didattiche, soprattutto a supporto delle attività di training necessarie per imparare ad utilizzare la nuova versione di un software.
Nel blog potrete trovare molte informazioni ben organizzate, dateci un'occhiata. Leggi questo articolo...

giovedì 24 dicembre 2009

BUONE FESTE A TUTTI !... Con qualche esercizio di stile...


BUONE E SERENE FESTE A TUTTI!

Mi permetto di darvi un'idea per fare un regalo.
Gli Esercizi di stile di Raymond Queaneau è un libro che chiunque dovrebbe leggere. Ma se poi vi capita la ventura, per lavoro o per diletto, di avere a che fare con la scrittura, allora questo libro diventa una specie di totem, un riferimento simbolico assoluto, un libro che SI DEVE LEGGERE.
Di libri che si devono leggere ce ne sono tantissimi e ognuno ha i suoi, ma alcuni sono "universali" e quando scrivete... questo è imperdibile. Un banale fatto di cronaca, descritto in decine di modi diversi, poche righe per ogni "esercizio di stile". Un virtuosismo sublime, che quasi stordisce alla prima lettura. Un libro tascabile, tradotto in italiano da Umberto Eco, ma in poche pagine c'è tutta l'essenza della letteratura. E che cosa avrebbe a che fare una gemma così preziosa, un capolovoro del '900 con un blog che parla di scrittura tecnica, da sempre considerata una forma di scrittura minore o di serie B? C'entra, c'entra... non immaginate nemmeno quanto.

SCOPRITELO! E TANTI AUGURI DI BUONE FESTE A TUTTI VOI! Leggi questo articolo...

mercoledì 23 dicembre 2009

Lavoro, lavoro, lavoro... ma anche una pausa divertente...

Vi segnalo questo sito divertente, che vi permette di giocare con le parole.
E' un generatore di "nuvole di parole"... non vi dico altro.
Provatelo! Leggi questo articolo...

martedì 15 dicembre 2009

Revisione di un testo: attenti al Diavolo!... o ai particolari...

"Il diavolo si nasconde nei particolari"... MA ANCHE LA QUALITA'!
E questo adagio vale anche per un testo. Sono certo di poter affermare che quasi nessuno riesce a scrivere, alla prima stesura, un testo ottimale o almeno sufficiente.
In questo blog c'è un'intera sezione dedicata alla riscrittura di un testo e mi sono già espresso sull'importanza di questo lavoro, spesso colpevolmente trascurato, fornendo anche una breve indicazione sul metodo che utilizzo di solito.
In un altro post vi ho anche fornito una check-list di criteri utili da usare durante la fase di analisi e riscrittura, invitandovi ad usarla.
Quando vi sembra che il vostro testo abbia assunto una forma sostanzialmente definitiva, quando tutti i criteri della check-list sono verificati, inizia una fase "di revisione qualitativa" finalizzata a limare le ultime asperità della vostra composizione.

Ma cosa significa effettuare una revisione qualitativa?

Significa assumere l'atteggiamento di un serial killer, spietato e maniacale, alla ricerca di tutti quei difetti che non sono stati rilevati nei passaggi precedenti. Per fare questo è necessario rileggere il testo in "diversi modi", impedendo cosi' al cervello di cadere nella trappola della rilettura ripetuta e "piatta", ma obbligandolo ogni volta a riguardare il testo come qualcosa di "diverso".

A tale scopo si applica una tecnica di rilettura STRATIFICATA.

In altri termini, si isolano alcuni aspetti del testo e si esaminano, ad ogni passaggio, SOLO QUEGLI ASPETTI.

Lo schema che vi propongo, come sempre, non è l'unico possibile. Ognuno può definire il proprio. Ma intanto provate ad usare questo, che è organizzato in 5 diversi passaggi.


CONTROLLO DEI CONTENUTI E DELLA LORO ORGANIZZAZIONE

Siamo riusciti a dire tutto quello che dovevamo dire? La divisione in capitoli e paragrafi è ben strutturata? Le conclusioni sono convincenti? Provate a leggere il tutto il documento, per avere un'idea della coerenza complessiva. Non fermatevi ad analizzare ogni difetto, ma annotate rapidamente i punti dubbi sui quali vorrete tornare.
Al termine decidete se i punti annotati sono degni di una riscrittura parziale o anche totale.
Se la percentuale dei vostri interventi, in questa fase, ha superato il 10% del testo complessivo, ripetete l'intero processo dall'inizio.


CONTROLLO DEI RIFERIMENTI

Controllate vostri riferimenti.
Se usate le parole di qualcuno, citatele tra virgolette. In alternativa, sviluppate la capacità di parafrasarle. Riportate con precisione le vostre fonti, sia che si tratti di bibliografia tradizionale o di una pagina web.


CONTROLLO DI GRAMMATICA E PUNTEGGIATURA

Più siete esperti e meno problemi rileverete in questa fase, ma per un principiante questo passaggio è fondamentale.
In particolare verificate le concordanze:

  • singolare/plurale
  • maschile/femminile
  • soggetto/verbo

ANALISI DI STILE

E' molto difficile dare una definizione di questa fase.
Io in genere opero solo su 3 aspetti:

  • la proprietà di linguaggio
  • l'eliminazione di ridondanze inutili e ripetizioni che incidono sulla scorrevolezza del testo
  • infine...ASCIUGARE IL TESTO!!!

... e l'ultimo è il più importante.
Anche qui siete liberi di arricchire questa fase con altri elementi, ma almeno questi tre li ritengo necessari.


CACCIA ALL'ERRORE NASCOSTO

Quando tutto sembra perfetto...

  • controllate eventuali refusi
  • le intestazioni e i piè di pagina
  • le liste numerate
  • il glossario
  • un titolo di un paragrafo che non riflette più il contenuto del medesimo
  • un’introduzione che cita qualcosa che poi non c’è
  • le coppie di parentesi e le coppie di virgolette
  • i numeri delle pagine
  • la concordanza indice/contenuto (capitoli, paragrafi, ...)
  • se usate note numerate, la concordanza numeri/note

ALTRO?

Forse si... ma già questo è più che sufficiente.
Se il vostro testo riesce a superare questo percorso ad ostacoli, sarà sicuramente migliorato rispetto alla prima stesura.
Leggi questo articolo...

giovedì 10 dicembre 2009

Il "blocco da pagina bianca"

Da qui alla fine di Dicembre dovrò consegnare diversi manuali.
E' un periodo di superlavoro. In periodi come questi, che si susseguono durante l'anno con una certa regolarità, tutto mi può succedere... meno che smarrire il filo "del mestiere". Uno degli incubi ricorrenti del writer è il "blocco da pagina bianca". La testa frulla idee e parole ma non si riesce a trovare il bandolo della matassa, l'inizio giusto, lo spunto.
Allora mi ricordo di una cosa letta non so quando e scritta da un grande scrittore come Richard Lee Rhodes, vincitore del Premio Pulitzer nel 1986:

If writing a book is impossible, write a chapter.
If writing a chapter is impossible, write a page.
If writing a page is impossible, write a paragraph.
If writing a paragraph is impossible, write a sentence.
If writing a sentence is impossible, write a word and
teach yourself everything there is to know about that
word and then write another, connected word and see
where the connection leads.

E' una specie di mantra.
Quandi siete in difficoltà provate ad usarlo... male non vi farà e come spesso accade alle cose semplici... funziona!
Leggi questo articolo...

domenica 6 dicembre 2009

Lettera d'Incarico: un secondo Template

Oggi vi propongo un secondo esempio di Lettera d'Incarico.

Il primo modello era incentrato su un incarico che il responsabile di un'azienda conferiva ad un dipendente dell'azienda medesima.

Qui si tratta invece di una lettera d'incarico che regola un rapporto tra privati.
In particolare, si tratta di una lettera in cui un committente conferisce un incarico ad un ragioniere/commercialista. Questo modello è più articolato e complesso rispetto al precedente e nasce da una sintesi di altri 3 modelli che ho preso in esame.

Gli elementi principali sono:

1) Oggetto dell'incarico

2) Decorrenza e durata dell'incarico

3) Compenso del Professionista

4) Interessi di mora

5) Obblighi del Professionista

6) Obblighi del Cliente

7) Clausola risolutiva espressa

8) Recesso

9) Polizza assicurativa

10) Elezione di domicilio

11) Rinvio al Codice Civile

12) Protezione dei dati personali

Come sempre, vi ricordo che ciò che vi propongo SONO SOLO DEI MODELLI DI RIFERIMENTO.
Non è detto che siano adatti, tal quali, per i vostri usi.
Prendeteli in esame e valutate come adattarli ai vostri bisogni.

Lo potete scaricare liberamente via SCRIBD, come gli altri che vi ho proposto.
Leggi questo articolo...

domenica 22 novembre 2009

Aggiungiamo le tabelle al nostro Template

Nel post del 7 Novembre 2009 vi avevo messo a disposizione un primo basic Template "general purpose", liberamente scaricabile via SCRIBD.
Ora aggungiamo qualche elemento.
Può essere molto utile disporre di un set di tabelle da utilizzare nei nostri documenti. Inoltre, può essere comodo anche avere un indice(sommario) che ci permette di rintracciare rapidamente tutte le tabelle che abbiamo disseminato nel nostro documento. In questo nuovo Template, nel Capitolo 3, trovate 3 tabelle rispettivamente a 2, 3 e 4 colonne:


Possono essere selezionate e quindi copiate e incollate in ogni punto del documento.
La didascalia posta alla base della tabella viene indicizzata attraverso l’indice delle tabelle, posizionato in fondo al Template. La numerazione è automatica ed è strutturata semplicemente così:

Tabella NUMERO CAPITOLO.NUMERO TABELLA - Didascalia

Per aggiornare la numerazione, basta selezionare il numero X.Y, quindi premere il pulsante destro del mouse; nel menù a tendina che viene visualizzato, selezionate Aggiorna campo.

Per analizzare le proprietà delle tabelle proposte, basta selezionare la tabella quindi premere il pulsante destro del mouse; nel menù a tendina che viene visualizzato, selezionate Proprietà tabella.


L'indice(sommario) delle tabelle ha una natura del tutto analoga a quella dell'indice generale del Template e si aggiorna con la modalità già illustrata nel post sopracitato.
Provate a scaricare questo secondo Template e ad utilizzarlo. Leggi questo articolo...

Scrivere per il Web... non è solo una questione di font.

Il mio collega Daniele mi ha segnalato un link molto interessante, che vi propongo a mia volta.
Quando si scrive per il Web spesso si pensa, erroneamente, che si debbano applicare le stesse regole tipografiche che si applicano nella scrittura classica in ambiti più tradizionali (libri, riviste, quotidiani, ...). In realtà, la scrittura per il Web è un'attività molto più ricca e consente soluzioni molto più potenti e complesse.
Proprio per questo è necessario assorbire e strutturare una competenza specifica, perchè non è detto che chi ha imparato a scrivere, anche professionalmente, in un ambito tradizionale, sappia poi essere parimenti efficace sul Web.
Gli spunti proposti da Mark Boulton sono sicuramente interessanti.
Come dico sempre, studiate, saccheggiate e "copiate" da quelli più bravi di voi... solo poi sarete in grado di impiantare soluzioni "vostre" ed originali.
Spero possa esservi utile. Leggi questo articolo...

lunedì 16 novembre 2009

Lettera d'Incarico: un primo Template

Nel post di ieri ho parlato della Lettera d'Incarico e ho fornito un semplice modello della medesima.
Come sempre, tale esempio non è certamente esaustivo di tutte la casistiche in cui può essere utile saper scrivere una lettera di questo tipo. Potete ora anche scaricare un Template congruente a quanto indicato nel post. Presto tornerò sull'argomento con un altro esempio e annesso Template.
Fatemi avere eventuali osservazioni che riterrete opportune, anche sull'efficenza di SCRIBD. A presto. Leggi questo articolo...

domenica 15 novembre 2009

Saper scrivere... la Lettera d'Incarico: un primo esempio

La "Lettera d'Incarico" è un classico della scrittura tecnico-commerciale.
Non è possibile individuare un solo modello general purpose per questa composizone.
Ci sono soluzioni adatte per definire i rapporti professionali che si vengono a stabilire tra due privati o tra un'azienda e un suo impiegato.
La struttura e i contenuti cambiano anche in base all'ambito professionale specifico, perche' possono mutare le normative e gli obblighi che devono essere specificati nella lettera.

In un'azienda, quando ad una persona viene assegnata una nuova posizione professionale, è d'uso ufficializzare tale evento con la Lettera d'Incarico.

Essa deve contenere alcuni elementi obbligatori, che sono:
  • il nome dell'azienda, la sede e la data in cui la lettera è stata redatta (generalmente in alto a destra);
  • il nome della persona che riceve l'incarico (sempre in alto a destra, sotto la sede e la data);
  • l'oggetto, che apre la lettera, in cui viene specificato l'incarico;
  • il nome dell'azienda e del Responsabile del settore/area/divisione che assegna l'incarico (generalmente in basso a destra);
  • il nome e la firma dell'incaricato (generalmente in basso a sinistra).

Altri elementi importanti sono di solito confinati nel corpo della lettera e identificano:
  • gli eventuali riferimenti normativi relativi all'incarico;
  • l'elenco delle principali caratteristiche dell'incarico.

In effetti, l'elenco delle caratteristiche dell'incarico costituisce la parte più qualificante della lettera. E' infatti in questa parte che si definiscono i compiti che il candidato designato andrà a ricoprire. Questa parte deve essere redatta con particolare attenzione, anche in relazione ai riferimenti normativi che contribuiscono a definire il profilo dell'incarico.

Di solito,la lettera si chiude sempre con una formula di questo tipo:

"Le ricordiamo inoltre l’obbligo di riservatezza e mantenimento del segreto in ordine ai processi lavorativi di cui verrà a conoscenza nell’esercizio delle funzioni svolte."

... che sottolinea l'obbligo alla lealtà e alla riservatezza che qualsiasi impiegato deve sempre rispettare nell'ambito della sua professione.

Di seguito, vi propongo un esempio:

Questa è la prima parte, in cui c'è proprio l'elenco delle caratteristiche principali dell'incarico di RSPPA (Responsabile Servizio Prevenzione e Protezione Aziendale).

Questa è la seconda parte, in cui, in calce, è prevista la firma del Responsabile e quella dell'incaricato. La lettera deve essere ovviamente realizzata su carta intestata dell'azienda che conferisce l'incarico. Generalmente non viene spedita, ma consegnata a mano, in busta chusa.

L'esempio che vi ho proposto è estremamente semplice ma rappresenta un buon modello di partenza per orientarsi sull'argomento.
Ritornerò sulla questione prossimamente.
Leggi questo articolo...

sabato 7 novembre 2009

Un primo semplice Template

Questo primo post inaugura una nuova sezione, in cui vi proporrò una collezione di template che spero possano fornirvi alcuni spunti utili per arrivare a definire I VOSTRI template. Li potrete visionare e scaricare via SCRIBD, uno tra i maggiori servizi per la condivisione di documentazione sul Web.

Questo è un esempio di basic/general purpose template, dal quale si può partire per strutturare via via dei modelli più accurati e ben costruiti per scopi specifici.
Ma visto che da quache parte bisogna pur cominciare...

Il template si compone di sole 8 pagine.


- PAGINA 1

Qui c'è la copertina (front-cover) del documento.
E' strutturata come una griglia costruita con una tabella costituita da una sola colonna e 5 righe:

La prima riga contiene il logo della vostra azienda.
La seconda riga ospita il nome del prodotto.
La terza riga è dedicata al nome del manuale.
Infatti, uno stesso prodotto puo' essere accompagnato da piu' manuali; ad esempio, nel caso di un prodotto software, l'Installation Manual, il Getting Started Manual e l'Administration Manual.
La quarta riga ospita la versione del prodotto.
La quinta è destinata al logo del prodotto.
Nella parte più bassa della pagina, la data di emissione del manuale.

- PAGINA 2


Qui trova spazio l'Avviso legale, espresso sia in italiano che in inglese, scritto in Arial 11.

La forma dell'Avviso non è oggetto di queto articolo, ne parleremo prossimamente.

- PAGINA 3

Qui è presente l'Indice.


E' un indice aggiornabile automaticamente.
A valle di una modifica del documento, che utilizza gli stili previsti nell'Indice, basterà selezionarlo con un click del pulsante sinistro del mouse; poi, con un click del pulsante destro, dal menù a tendina selezonare la voce Aggiorna campo e, successivamente, Aggiorna intero sommario.


Su come relizzare un Indice o Sommario, per ora vi rimando al manuale di Office Word.

- PAGINA 4

Qui trovate il Capitolo 1

- PAGINA 5

Qui trovate il Capitolo 2, ove sono elencati gli stili disponibili per 5 livelli di titolo.
Per utilizzarli, basta selezionarli ed effetture un copia-incolla in ogni altra parte del documento.
La numerazione si aggiornerà automaticamente.

- PAGINA 6

Qui trovate il Capitolo 3

- PAGINA 7

Qui trova spazio la Bibliografia.
Vi sono diverse convenzioni per strutturare una Bibliografia.
In questo template viene utilizzata una struttura semplice ed efficace, ma non è detto che sia la più adatta ai vosti scopi... del resto, non abbiamo detto che è un template General Purpose?
La struttura è automatica; posizionatevi in fondo all'ultima riga e premete il pulsante Invio.
La riga successiva verrà generata automaticamente.

- PAGINA 8

Pagina di chiusura, rigorosamente vuota... per ora!

Provate a scaricarlo e ad utilizzarlo.
E' molto spartano, ma già presenta una struttura ben caratterizzata.
Prossimamente lo arricchiremo, per migliorarlo in ogni suo aspetto.
Buon lavoro!
Leggi questo articolo...

venerdì 6 novembre 2009

Scusate l'assenza...

Ho attraversato un periodo pesante. Tanto lavoro, qualche problema di salute in famiglia ma anche nuove idee per parecchi nuovi post. Abbiate pazienza...
Per ora vi segnalo alcuni buoni consigli per chiudere una
mail professionale.
A presto. Leggi questo articolo...

sabato 17 ottobre 2009

Un esempio di comunicazione efficace: il Manifesto del Celiaco

Mia moglie è celiaca. La celiachia è una malattia autoimmune che impedisce l'assunzione del glutine, una sostanza presente in un gran numero di alimenti, principalmente pane, pasta e tutti i derivati del grano e affini. Per illustrare la sua esperienza nel percorso attraverso questa patologia, ha deciso di realizzare un blog, Puntodivistaceliaco. E da questo blog, tra le altre cose, potete scaricare il Manifesto del Celiaco, una brochure che in un singolo foglio riassume e sintetizza una serie di osservazioni essenziali che forniscono un quadro istantaneo della malattia celiaca e dei presidi d'attenzione che devono essere messi in atto quando si prepara un pasto per un celiaco.
Il Manifesto è un piccolo capolavoro di comunicazione. Provate ad esaminare un qualsiasi argomento e provate a condensare in una sola pagina, in sole 15 frasi, tutte le coordinate che consentono di circoscrivere l'argomento. Vi assicuro che non è per nulla facile. Se non sapete nulla sulla celiachia, il Manifesto vi fornisce tutti i dati fondamentali, attraverso messaggi brevi e chiari, nonchè i riferimenti all'AIC (Associazione Italiana Celiachia). Leggi questo articolo...

Un buon esempio di Tutorial

Da alcuni anni siamo ormai abituati a relazionarci via Internet con la Pubblica Amministrazione e con diversi Enti Pubblici. Governo centrale, Regioni, Province, Comuni ed Enti previdenziali oggi dispongono di siti Web che forniscono diversi tipi di informazioni.
Non sempre i contenuti di questi siti sono all'altezza delle aspettative degli utenti e sarebbe abbastanza facile fare l'elenco delle manchevolezze grossolane che spesso ho rilevato. Ma stavolta voglio proporvi un esempio "in positivo".
Si tratta del sito dell'INPS (Istituto Nazionale Previdenza Sociale), che mette a disposizione degli utenti molti utili dati. Per accedere a tali dati, è necessario effettuare una registrazione, a valle della quale vi sarà fornito un PIN (Personal Identification Number).
Una volta ottenuto il PIN, si potrà effettuare il login ed accedere ad un insieme di informazioni che riguardano la nostra storia contributiva e altro ancora.
MA COME SI OTTIENE IL PIN? Con pochi semplici passaggi che sono illustrati da un breve ed efficace Tutorial consultabile on-line, nella sezione GUIDA ALL'ASSEGNAZIONE.
E' un ottimo esempio di come si possa facilitare la vita agli utenti, spiegando in soli 4 passi tutto ciò che necessita per l'ottenimento del PIN.
La veste grafica è molto elementare e si potrebbe fare di meglio, ma è in linea con l'aria di "semplicità" che permette all'utente di concentrarsi sui passaggi essenziali della procedura.
Dateci un occhiata. Leggi questo articolo...

domenica 11 ottobre 2009

Soluzioni: facciamoci...le note degli altri!

Ora vediamo come vengono usate le note nei manuali di alcuni tra i maggiori vendors del mondo ICT.
Nei suoi manuali la SUN usa una forma molto sobria per proporre la nota:

Questo stile non mi convince, se una nota è "troppo sobria" rischia di non essere... notata!
La Microsoft in alcuni manuali (ad esempio, nei manuali che si usano per preparare una certificazione), usa ben 10 tipolgie di note:


Francamente mi sembra un eccesso di zelo; tuttavia, nell'ottica di un manuale che devo usare per ottenere una certificazione, questo approccio molto differenziato può avere una valenza didattica degna d'attenzione.

HP in molti manuali utilizza una modalità meno dettagliata rispetto a quella utilizzata da Microsoft, ma comunque efficace e strutturata su 4 tipi di note distinte:

Se possiamo ravvisare un difetto, dobbiamo dire che le icone utilizzate per indicare la nota non sono molto caratterizzate dal punto di vista grafico e non colpiscono sufficentemente l'occhio.

Anche nei Redbooks della IBM potete trovare diversi tipi di note.
Di seguito ne riporto soltanto 3 a titolo di esempio:




Lo stile di IBM è anch'esso molto sobrio, tuttavia la nota, grazie allo sfondo grigio, emerge in modo molto distinto rispetto al testo.

Come potete vedere da questi esempi, ogni vendor usa uno stile diverso, ma tutti utilizzano le note "in prossimità" del contesto a cui si riferiscono, rifuggendo quindi dallo stile classico della nota a piè di pagina o dalle note di chiusura, di cui vi ho fatto cenno nel post precedente.
Potrei fare molti altri esempi, ma lo scopo di questo post non è fornire una tassonomia di tutti i modi possibili di proporre una nota.

Quello che mi interessa sottolinare è che quando scrivete un documento tecnico, dovete fare attenzione a questo aspetto: mettete sempre in primo piano gli elementi essenziali di un discorso, la linea di pensiero fondante, il percorso concettuale fondamentale che l'utente deve seguire con attenzione.
Tutti gli elementi complementari e asincroni rispetto alla linea generale, possono essere evidenziati con delle note, posizionate "in prossimità" del flusso generale.

Nei post futuri vi proporrò qualche esempio per chiarificare la questione.
Leggi questo articolo...

sabato 3 ottobre 2009

Soluzioni: nota la NOTA!

In un documento tecnico è spesso utile far ricorso all'uso delle note, ma è necessario non abusarne inutilmente.

La nota tipicamente serve a puntualizzare o aggiungere elementi di conoscenza sul concetto che viene espresso e illustrato nel corpo principale del testo, in modo da non appesantire il testo medesimo.

Essa spesso fornisce informazioni "asincrone" rispetto al flusso primario, cioè informazioni complementari ma che nel corpo del testo potrebbero comunicare un fastidioso effetto "deviazione" della linea di pensiero principale.

Un esempio può essere utile a chiarire il concetto:

"...il modello è costituito da 5 elementi principali: gli Utenti, le Unità Organizzative, i Ruoli, i Profili e le Risorse. Le relazioni che intercorrono tra questi elementi..."

Il testo proposto descrive un generico modello, i suoi elementi principali e le relazioni tra tali elementi. Se abbiamo bisogno, in questo frammento, di aggiungere una distinzione tipologica tra gli Utenti che popolano il modello, possiamo usare una nota:

"... NOTA - Gli Utenti del modello possono essere suddivisi in 4 tipologie distinte: TIPO 1... TIPO 2... TIPO 3... TIPO 4... "

Ovviamente, potevamo scegliere di inserire il contenuto della nota nel corpo del testo principale, ma avremmo ottenuto per l'appunto l'effetto "deviazione", cioè avremmo costretto il lettore a deviare la sua attenzione dalla linea principale del ragionamento, finalizzata a descrivere gli oggetti critici del modello (entità e relazioni tra di esse), per acquisire delle informazioni certamente importanti ma che possono più utilmente essere proposte in un punto diverso.

Non ci credete ?

"...il modello è costituito da 5 elementi principali: gli Utenti (gli Utenti del modello possono essere suddivisi in 4 tipologie distinte: TIPO 1... TIPO 2... TIPO 3... TIPO 4...), le Unità Organizzative, i Ruoli, i Profili e le Risorse. Le relazioni che intercorrono tra questi elementi..."

Non mi sembra un granchè... molto meglio usare la nota.
Ma come identifichiamo la nota ? E dove la collochiamo ?

Distinguiamo principalmente tra:
  • nota a piè di pagina (footer), collocata in fondo ad una pagina;
  • nota di chiusura, collocata al termine del capitolo o alla fine del documento.
Classicamente, le note vengono richiamate da un numero posizionato in alto a destra della parola che necessita dell'annotazione. Possono essere numerate consecutivamente lungo tutto il testo, oppure si può usare una numerazione localizzata per ogni capitolo, ripartendo dal numero 1 all'inizio di ogni nuovo capitolo.

In alcuni contesti, le note devono essere utilizzate seguendo regole tipiche di quel contesto (ad esempio, nel caso di lavori scientifico-accademici si useranno le regole definite per le pubblicazioni di quel genere).

Io ho un'approccio abbastanza personale sull'argomento.

In primo luogo, detesto le note di chiusura. Le note spostate alla fine del capitolo (figuriamoci alla fine del documento) non servono a nulla e perdono completamente la loro utilità; le odiavo fin dai tempi in cui studiavo all'Università e non le uso mai nei miei documenti.
Immaginate una nota a pagina 13 di un capitolo di 70 pagine... per andarla a leggere devo scorrere in avanti, leggere la nota e ritornare a pag. 13... MA NON S'ERA DETTO CHE L'EFFETTO "DEVIAZIONE" ERA FASTIDIOSO ?

Non uso nemmeno le note numerate, perchè credo nel potere evocativo delle immagini.
Dovendo scrivere principalmente Manuali Tecnici nell'ambito ICT, uso due icone ben distinte, che identificano due tipi di note:

NOTE DI ATTENZIONE: vanno utilizzate per annotazioni critiche, che NON devono essere ignorate dal lettore, onde evitare danni o problemi.





NOTE DI OSSERVAZIONE: vanno utilizzate per annotazioni che rivestono un interesse specifico, ma che se ignorate non implicano particolari danni o problemi.





Le due icone colpisono l'occhio del lettore e prima ancora di leggerne il contenuto egli è già è avvisato della valenza della nota. Tali note sono collocate "in prossimità" del testo a cui si riferiscono, quindi non alla fine del capitolo.

Di seguito è illustrato un esempio:











Al prossimo post per esaminare COME USANO LE NOTE alcuni tra i più importanti vendors del mondo ICT.

Leggi questo articolo...

giovedì 24 settembre 2009

PRIMO ASSIOMA UNIVERSALE del TW

SE IL PRODOTTO ESISTE E IL MANUALE NON ESISTE,
IL PRODOTTO NON ESISTE.

SE IL PRODOTTO NON ESISTE E IL MANUALE ESISTE,
IL PRODOTTO ESISTE.


Chi ha formulato per primo questo atipico assioma?

Probabilmente io... ma quasi certamente no.
Nel senso che lo penso e lo affermo, quindi lo enuncio, sulla scorta di letture effettuate, traendo spunto dal lavoro di TWs più esperti di me e sintetizzando un insieme di esperienze, tra cui le mie.
Ma alla fine fine l'eventuale paternità di questo giochino dialettico è una ben povera questione.

E' invece molto più importante osservare che anche se avete il prodotto migliore del mondo, se non sarà accompagnato da un adeguato set di documenti, nessuno potrà apprezzarlo. Aggiungo che l'attività di marketing in tal senso non è meno importante della documentazione tecnica specifica, tanto per avvalorare oltremodo l'assioma.

Perchè ho definito l'assioma "atipico"?
Perchè gli assiomi non si dimostrano; ma questo, pur non avendo alcun bisogno di essere dimostrato.. E' DIMOSTRABILE! Non ci credete?
Due veloci esempi:
  • il movimento Open Source
  • IKEA
Quando andavo all'Università, i Linux guru erano ammantati di un alone di santità o erano indicati come l'incarnazione più affascinante del "carbonaro-hacker-anarchico" dell'informatica.
Ma se qualcuno pensa che l'Open Source, ormai diventato uno dei motori più importanti dell'ICT Business, debba il suo successo al genio genialoide di pochi eletti, il cui capostipite è Linus Torvalds, sbaglia clamorosamente.
Il segreto del successo del mondo Linux e affini è basato sugli "HOW-TO", cioe SUI DOCUMENTI, spartani ma efficaci, che ogni appassionato sviluppatore Opens Source produce a supporto del suo lavoro, consentendo a tutti gli altri di capire CHE COSA si è sviluppato e COME FUNZIONA.
Senza gli HOW-TO forse l'Open Source sarebbe morto nella culla, ucciso dal morbo dell'inutilizzabilità di soluzioni non adeguatamente documentate.

IKEA può essere definito come un modo di pensare l'arredamento in "filosofia RISC" (Reduced Instruction Set Computer), che tradotto per i non informatici significa "badiamo al sodo".
Una delle principali carte vincenti di IKEA sono i libretti d'istruzione per il montaggio dei mobili.
I suoi fan sostengono che siano chiarissimi e che montare un mobile attraverso di essi risulta essere particolarmente semplice... ed economico, perchè consente un risparmio non banale sul prezzo del mobile medesimo.
Quindi anche per IKEA, la qualità della documentazione associata ai prodotti non è un fastidioso orpello ma un elemento importante della sua logica di Business.

Vi sfido a fornire una tesi convincente in grado di smontare l'assioma... buona fortuna!

P.S.

... ne avrete bisogno ...
Leggi questo articolo...

mercoledì 23 settembre 2009

Ancora sugli acronimi ... e affini

In questo post, che conclude il trittico composto dagli articoli del 12 Agosto e del 18 Agosto, vi propongo alcune annotazioni da tenere a mente.

Un acronimo può essere influenzato dalla lingua d'origine.

In Italia abbiamo sempre sentito parlare dell'OLP (Organizzazione per la Liberazione della Palestina), ma nei paesi anglosassoni avremmo sentito parlare di PLO (Palestine Liberation Organization).

Così come in Francia sentirete indicare come SIDA la malattia che tutto il resto del mondo chiama AIDS (Acquired Immune Deficency Syndrom).

Quindi si deve porre attenzione, in alcuni casi, all'utilizzo dell'acronimo espresso nella forma più adatta alla lingua di chi poi dovrà interpretarlo, anche perchè molti acronimi sono diventati ormai di uso comune, al punto che qualcuno li usa alla stregua di "parole" vere e proprie (USA, JFK, RAM, CD, FIAT, ENEL, ONU, FAO, ...).

In molti settori tecnico/scientifici esistono regole specifiche e acronimi/sigle "speciali" che devono essere appropriatamente utilizzati.

Nel campo della Chimica, ad esempio, il Rame è Cu (dal latino Cuprum), l'Oro è Au (Aurum), il Carbonio è C (Carbonium) e l'Elio è He (Helium).
Il Metano è CH4 (derivante direttamente dalla formula di struttura del Metano, la cui molecola è formata da un atomo di Carbonio e 4 di Idrogeno).
I CloroFluoroCarburi (i composti responsabili del buco dell'Ozono, scoperti negli anni '30 del secolo scorso), vengono indicati con un acronimo "vero e proprio", CFCs, derivante dall'espressione inglese (Chlorofluorocarbons).
Gli isotopi di uno stesso elemento vengo indicati dal nome stesso dell'elemento seguito da un codice numerico o, equivalentemente, dal simbolo dell'elemento preceduto dal suddetto codice numerico.

Ad esempio:
Carbonio 14 --> 14C
Elio 3 --> 3He

Come vediamo quindi, in quest'area esiste un set di regole per la nomenclatura di elementi sempici e dei composti, che sono regole PROPRIE E SPECIFICHE di questo settore.

Questa osservazione può essere ritenuta valida in ogni altro campo.

In ambito commerciale/legale, ad esempio, è largamante usata, soprattutto nel mondo anglosassone, la & ('e' commerciale) per associare due o tre nomi/soggetti che identificano il nome di una società.
Ad esempio, Goldman&Sachs (G&S), Dolce&Gabbana (D&G), AT&T e così via.

Nell'ambito della Fisica, le diverse grandezze fisiche vengono espresse secondo le regole previste dal Sistema Internazionale.

Questi e altri esempi che potrei continuare ad esporre, ci indicano chiaramente che quando ci apprestiamo a scrivere un documento tecnico relativo ad un ambito ben definito, dobbiamo conoscere le regole di nomenclatura e le convenzioni simboliche proprie di quell'ambito.

A QUESTO PUNTO... abbiamo finito con gli acronimi? OVVIAMENTE NO!

Ma spero che i concetti basilari esposti possano aiutarvi ad eliminare almeno gli errori più comuni, che spesso mi capita di rilevare.
Per poter sopravvivere "nell'inferno degli acronimi", vi segnalo due siti che possono essere utili:

www.acronyma.com

www.pchell.com/acronyms

Se ne trovate altri, segnalatemeli!
Leggi questo articolo...

domenica 6 settembre 2009

Ma quale template per i nostri documenti?


Ormai siamo convinti che dobbiamo utilizzare un template per realizzare il nostro manuale.
MA USEREMO UN SOLO "general purpose" template o dobbiamo avere dei template specifici per ogni tipo di documento? La risposta più corretta, ma anche la più banale, è la seconda.
Per ogni documento dobbiamo utilizzare il template più adatto, che meglio delimita il tipo e la qualità dei contenuti che devono essere organizzati per uno scopo specifico.

Ad esempio, in un Installation Manual dovremo predisporre una sezione PREREQUISITES che dovrà ospitare tutte le indicazioni preliminari che devono essere verificate prima di iniziare il processo d'installazione.

Se invece dobbiamo realizzare un Getting Started Manual, assumiamo che il prodotto sia stato correttamente installato e non abbiamo bisogno di specificare alcun prerequisito.

All'inizio tuttavia non è semplice individuare correttamente tutti gli elementi che devono essere collocati in un template.

Posso azzardare due consigli:
  • COPIATE DAI MIGLIORI
  • INDIVIDUATE UN TEMPLATE "FLESSIBILE" E MIGLIORATELO PROGRESSIVAMENTE
Il primo consiglio è forse il migliore possibile.
Non siate presuntuosi, nessuno inventa nulla. Prima di poter proporre qualcosa di VERAMENTE ORIGINALE dovete studiare molto e... COPIARE molto. Solo quando sarete veramente padroni del vostro mestiere (alcuni anni ?...) potete tentare di impiantare soluzioni innovative. Nell'attesa, guardate cosa fanno gli altri (IBM, HP, SUN, MICROSOFT...), che vantano esperienze decennali e investono ogni anno risorse ingenti nella produzione di documentazione. Ispiratevi... vi assicuro che non è una perdita di tempo.

Il secondo sembra contraddire la prima parte di questo post, ma solo in apparenza. Si inizia con un template "general purpose", robusto e flessibile, e poi via via si specializza.
Ok, ma in pratica... che vuol dire ?
Lo vedremo presto... abbiate pazienza.
Ciao!
Leggi questo articolo...

mercoledì 26 agosto 2009

Chi trova un template... trova un tesoro!

Dopo aver stabilito quali/quanti documenti devono accompagnare il nostro prodotto, ci troviamo davanti alla prima pagina bianca del primo manuale.
E' un evento inevitabile e il "panico da foglio bianco" è una sensazione ben nota, che tutti noi abbiamo provato almeno una volta nella vita.
Esistono diverse tecniche per esorcizzarlo e di certo sarebbe utile disporre di un "template", cioè di un modello che, fin dall'inizio, ci aiutasse a delimitare la forma e la struttura dei contenuti che dobbiamo articolare.

PERCHE' USARE UN TEMPLATE?

In primo luogo, semplicemente perchè consente di risparmiare una gran quantità di tempo che, come ben noto, è denaro.

In secondo luogo, perchè l'omogeneità stilistica è uno dei principali parametri per identificare la qualità di un documento.

Non ci credete? Provate a scaricare, dal sito istituzionale della IBM, due o tre Redbooks.
Apriteli in sequenza, uno dopo l'altro, saltellando a caso fra i contenuti. Non è necessario essere un esperto di informatica, anzi non è necessario nemmeno capire cosa state leggendo, per "avvertire" la qualità di questi documenti. La loro sobria ed efficente solidità stilistica, di per se stessa, vi trasmetterà istantaneamente la sensazione di un oggetto "ben realizzato" e questo è importante.

In tal senso, un insieme ben definito di template permette di realizzare un insieme di documenti che contribuiscono al brand della vostra azienda. Cosa c'è di peggio che inviare al cliente di turno un set di manuali con un "look and feel" non omogeneo, disordinato e privo di un stile riconoscibile come quello "proprio" dell'azienda ?

A differenza della documentazione di marketing, che deve colpire la fantasia del cliente, sollecitandolo con meccanismi anche aggressivi o sorprendenti, ben noti agli esperti di pubblicità, la documentazione tecnica deve essere "rassicurante" e facile da usare; se vi abituate ad utilizzare dei template ben strutturati, potrete raggiungere questo obiettivo più agevolmente.

Un template può contenere diversi elementi, alcuni dei quali sono elencati di seguito:

- lo stile e la struttura della copertina (front cover)
- lo stile dell'indice generale del documento

- gli stili dei paragrafi usati nel documento
- i livelli di profondità dei titoli e dei paragrafi

- il layout di ogni elemento di ogni pagina

- lo stile dell'header e del footer

- lo stile dele tabelle

- lo stile delle note

- lo stile e la struttura del glossario

- lo stile e la struttura della bibliografia

- lo stile e la struttura della quarta di copertina (back cover)
- altro ancora...


E' impensabile, per ogni documento di ogni prodotto, ridefinire ogni volta da zero tutti questi elementi che possono esser strutturati solo a valle di un gran lavoro di progettazione e design, quasi sempre attraverso raffinamenti successivi, che richedono tempo ed esperienza.
Nell'azienda in cui lavoro, ho impiegato circa 3 anni per mettere a punto, per approssimazioni progressive, un certo numero di template efficaci e ritengo di dover ancora migliorarne alcuni aspetti, senza considerare tutti i template che devo ancora mettere a punto.

Un template ben fatto può essere riutilizzabile da writers diversi, che non dovranno preoccuparsi di definire la struttura del documento ma potranno focalizzarsi solo sui contenuti.

Un template consente di ridurre gli errori.
Ad esempio, la versione di un prodotto viene di solito riportata nel titolo del manuale, nella quarta di copertina e nel footer di ogni pagina. Legando questi elementi con un "campo dinamico", sarà possibile apportare le necessarie modifiche in ogni punto del documento, semplicemente modifcando tale campo; un writer poco accorto invece, si metterebbe a modificare "a mano" questa informazione in tutti i punti del documento in cui essa compare, con un notevole dispendio di tempo e rischiando quasi certamente di non riuscire ad aggiornare correttamente tutti i riferimenti presenti.

Insomma, non c'è veramente nessun buon motivo per non usare un template.
Il tempo che inizialmente dovrete investire per costruire un buon template, lo riguadagnerete cento volte in seguito.

In futuro, nella sezione Templates, troverete la descrizione della struttura di diversi template, ognuno con le sue peculiarità, che poi potrete liberamente scaricare da Scribd, uno dei più noti servizi per condividere documentazione.
Leggi questo articolo...

venerdì 21 agosto 2009

Un esempio di comunicazione efficace

Vi segnalo www.writingmatters.typepad.com/blog/, un'ottima fonte d'ispirazione per affinare le nostre capacità nel mare insidioso della business/technical communication. Volete un esempio ? Quante volte ci è capitata una pagina web con il classico ERROR 404 (File/Page Not Found) ...nudo e crudo e null'affatto "user-friendly", specie per gli utenti meno esperti?
Molti tecnici avrebbero molto da imparare su come deve essere comunicato all'utente il comportamento di un'applicazione web.
Ecco un esempio mirabile di come costruire una pagina efficace per "accompagnare" un ERROR 404:


Qui potete valutare l'articolo completo e prendere confidenza con molti altri contenuti interessanti e spero utili per il vostro lavoro.
E poi, per chiudere l'argomento in allegria, ecco 100 pagine divertenti sull'ERROR 404.
Come dire... "ad ognuno il suo"! Leggi questo articolo...

martedì 18 agosto 2009

La Babele degli acronimi: seconda parte


Come abbiamo visto nel post del 12 Agosto, l'uso degli acronimi è assoggettabile a regole precise, pur tenendo presenti le debite eccezioni. Ora analizziamo altri aspetti.

L'acronimo può essere confuso con "il marchio" di un'azienda.

Un esempio tipico è quello dell'ENEL (Ente Nazionale per l'Energia eLettrica).

Nel marchio di quest'azienda è visibile invece la sigla Enel, con la sola E maiuscola iniziale. Ecco un esempio in cui, se non vi sono possibili ambiguità, si può scrivere ENEL o Enel indifferentemente, in quanto l'uso ha determinato un'equivalenza delle due modalità, con una sostanziale sovrapposizione tra acronimo e marchio. Ma scrivere 'enel' è invece un errore.

Allo stesso modo, è ormai invalso l'uso equivalente di FIAT e Fiat.
Ma se scrivete 'fiat' qualcuno penserà che state scrivendo una parola latina.

Questo meccanismo è comune a moltissimi acronimi, cioè in tutti quei casi in cui l'uso ha ormai sovrapposto l'acronimo e il marchio/sigla equivalente.

Altro caso è quello del LASER (Light Amplification by Stimulated Emission of Radiation), che viene citato anche come Laser o l'equivalente 'laser'; quindi potrete trovare indifferentemente LASER, Laser o laser.

Nel caso della NATO (North Atlantic Treaty Organization) invece, tale meccanismo non si è affermato; troverete sempre scritto NATO e qualsiasi eccezione è un errore.

Questi esempi avvalorano la regola generale: se scrivete ENEL, FIAT, LASER e NATO siete sicuri di non sbagliare. Se usate invece le altre forme, dovete valutare il contesto e la consuetidine ormai consolidata, ma rischiate di commettere errori.

E' invece ormai caduta in disuso la notazione "puntata", in cui le lettere dell'acronimo sono separate dal '.'.

Quindi NATO e non N.A.T.O, LASER e non L.A.S.E.R. e così via.

Abbiamo finito ? No... al prossimo post.
Leggi questo articolo...

mercoledì 12 agosto 2009

La Babele degli acronimi: prima parte

"...L'applicazione necessita di almeno 1 GB di RAM. Essa si basa sui più diffusi protocolli e standad aperti (HTTPS, SSL, FTP, LDAP, XML, WSDL, SOAP, ...) e consente di implementare policies conformi alla SOA, nell'ambito di architetture GRC in cui...".

Avete capito qualcosa?
Se non siete dei consulenti del mondo ICT (?!?...un altro acronimo...) probabilmente no.

"The acronyms' hell" è il pane quotidiano di un TW e quasi ogni giorno spuntano nuovi acronimi in ogni settore tecnico.

Nel campo in cui opero, quello dell'Information&Computer Technology (ICT!... ecco che vuol dire!), questo aspetto è particolarmente critico, perchè è praticamente impossibile non ricorrere all'uso degli acronimi; d'altra parte, un loro uso smodato, così come mostrato nell'esempio iniziale, può conferire al testo una cripticità intellegibile solo agli addetti ai lavori.

Ci sono delle regole a cui affidarsi ? Certamente si, ma laddove ci sono delle regole, ci sono anche le relative eccezioni. Come in altri post di questo blog, cercherò di delineare gli elementi essenziali di quest'argomento, senza la pretesa di esaurirlo in ogni suo aspetto.

Un acronimo è una parola formata con le lettere iniziali di determinate parole di una frase o di una definizione.

In una accezione più "lasca", sarà possibile formare un acronimo anche a partire da alcun sillabe, non solo dalle iniziali, del gruppo di parole considerate.

Alcuni esempi di acronimi derivanti dalla definizione "stretta":

- SSL: Secure Socket Layer

- FTP: File Transfer Protocol

- FIGC: Federazione Italiana Gioco Calcio

- FIAT: Fabbrica Italiana Automobili Torino

... ed altri esempi derivanti dalla definizione "lasca":

- XML: eXtensbile Markup Language

- DNA: DeoxyriboNucleic Acid

- EURATOM: EURopean ATOMic Energy Community

La regola fondamentale, CHE NON PUO' MAI ESSERE DISATTESA, è quella che NON SI DEVE USARE MAI UN ACRONIMO senza specificare, alla prima citazione, l'espressione estesa alla quale quell'acronimo si riferisce.

Alcuni esempi?

"... la BCE (Banca Centrale Europea) ha emanato i nuovi valori dei tassi che saranno in vigore per i prossimi 3 mesi. Le aspettative degli analisti, che prevedevano una diminuzione dello 0.25, sono state disattese; il Presidente della BCE ha motivato le scelte effettuate con la necessità...".

Come si vede dall'esempio, si usa l'acronimo BCE e subito dopo, tra parentesi tonde, si indica l'espressione estesa, con le lettere che formano l'acronimo in maiuscolo. Successivamente, si usa l'acronimo senza più specificare la sua espressione estesa.

Altro esempio:

" ... la comunicazione delle credenziali dell'utente avviene su un canale sicuro, secondo le modalità previste dal protocollo SSL (Secure Socket Layer). Un canale SSL consente...".

CI SONO ECCEZIONI A QUESTA REGOLA ?

Si e dipendono dal contesto, nonchè dal "lettore target" a cui state pensando mentre scrivete.
Se state scrivendo un articolo su una rivista di auto e vi riferite al mercato dell'automobile in Italia, potete usare l'acronimo FIAT senza dover citare la sua dizione estesa.
Se state preparando una relazione da leggere ad una riunione di esperti genetisti, potete usare il termine DNA senza altra cautela.

In altri termini, potete usare un acronimo senza accompagnarlo con la sua espressione estesa, SOLO SE NEL CONTESTO IN CUI LO UTILIZZATE non vi è alcun dubbio in merito alla sua interpretazione.

All'inzio del post ho citato un brano tratto da una scheda tecnica di un prodotto software.
Per un esperto di ICT, il brano è abbastanza chiaro ma c'è l'ultimo acronimo, GRC, che può dar luogo a dubbi. GRC vorrà dire... Governance Risk Management and Compliance... oppure ... Governance Risk Control... oppure ... General Review Control... oppure ... ?!?

Ecco un bell'esempio in cui alcuni acronimi (SSL, XML, SOAP, ...) possono essere citati senza alcuna cautela, perchè siamo certi che il lettore target per il quale scriviamo non avrà dubbi nell'interpretarli, mentre altri vanno accompagnati dalla corretta espressione estesa (Governance Risk Management and Compliance).

Abbiamo esaurito l'argomento ? Ovviamente no... al prossimo post per esplorare altri aspetti degni di attenzione.
Leggi questo articolo...

mercoledì 29 luglio 2009

Eccomi a voi con questa mia a dirvi...

..."ADDIRVI... tutta una parola!", come diceva il principe Antonio De Curtis, in arte Totò, nella celeberrima e immortale scena della redazione della lettera, con Peppino De Filippo, in "Totò, Peppino e la malafemmina".

Dunque, a dirvi... che sono tornato dopo due settimane di corso d'Inglese full-immersion in cui, mentre tentavo di migliorare la mia conoscenza della lingua, ho abbozzato una serie di idee per molti nuovi post che vi proporrò prossimamente.
Per ora... un mini set di semplici acronimi che si possono usare (ma senza esagerare...) in una mail professionale, specialmente se avete maturato una particolare confidenza con il destinatario della medesima:
  • ASAP as soon as possible
  • NRN no reply necessary
  • FYI for your info
  • RFI request for information
  • PCM please call me
  • LMK let me know
Prendo spunto da questa idea per sottolineare che l'uso degli acronimi, nell'ambito della Business Communication, è soggetto a delle regole ben codificate, che in quanto tali possono però contemplare delle eccezioni.

Presto dedicherò un post proprio a questo argomento, particolarmente critico nell'ambito dell'Information and Computer Technology, ove gli acronimi proliferano come i funghi nel bosco a Settembre. Leggi questo articolo...

mercoledì 15 luglio 2009

Quali documenti... per quale prodotto?

Nel post del 2 Luglio ho fornito una roadmap minima attraverso la quale è possibile pianificare la produzione della documentazione di un'azienda. In funzione del contesto, tale roadmap può essere arricchita e diversificata.
Ma supponendo di partire da zero, gli elementi indicati sono da ritenersi gli elementi di base necessari da cui possiamo partire per organizzare il nostro lavoro.

A questo punto, chiediamoci COSA dobbiamo documentare e QUALI/QUANTI documenti dobbiamo mettere in cantiere a tale scopo.
Io lavoro in un'azienda IT che realizza prodotti software, in un'area di mercato altamente specializzata. Nel mio caso, per documentare un singolo prodotto, è sempre necessario realizzare ALMENO i seguenti documenti:

- BROCHURE: è il documento di marketing che fornisce, al cliente potenziale, le prime informazioni fondamentali sul prodotto.

- TECHNICAL SPECIFICATION: è il documento di sintesi che racchiude tutte le informazioni tecniche necessarie sul prodotto.

- INSTALLATION MANUAL: è il documento che fornisce tutte le informazioni per installare ed eventualmene configurare il prodotto.

- GETTING STARTED MANUAL (QUICK START GUIDE): è il documento che consente di prendere confidenza rapidamente con tutte le funzionalità di base del prodotto.

- ADMINISTRATION MANUAL: è un documento che contiene tutte le informazioni dettagliate, spesso in modalità Tutorial, rivolto ad un utente "evoluto", destinato al ruolo di Amministratore del prodotto e che quindi deve conoscere ogni aspetto del medesimo.

Perchè li ho elencati con la dizione inglese ?
Perchè abbiamo deciso di scrivere la documentazione di prodotto in inglese, visto che il mercato al quale ci rivolgiamo non è limitato all'interno dei confini nazionali.

Poi è spesso necessario mettere a punto altri documenti quali:

- USER MANUAL: è un documento rivolto ad un utente che deve usare il prodotto (tipicamente un sottoinsieme delle funzionalità disponibili nel prodotto) ma non ha le esigenze dell'utente a cui è dedicato l'Administrator Manual.

- INTEGRATION MANUAL: è un documento che descrive in che modo è possibile integrare il prodotto in un'architettura software pre-esistente, o l'aggiornamento del prodotto rispetto ad una versione precedente gia installata nel sistema ospite.

- API REFERENCE MANUAL: è un documento, finalizzato ad un tecnico programmatore, che descrive le librerie software eventualmente associate al prodotto.

Inoltre, all'interno delle applicazioni software, è necessario predisporre un HELP in formato HTML, i cui contenuti possono essere mutuati da uno o più manuali tra quelli elencati ma che richiedono un lavoro di filtro e formattazione che non può essere realizzato attraverso un banale
e meccanico "copia e incolla" di quanto già realizzato.

Ogni singolo prodotto deve poi essere testato e collaudato e questo richiede lo sviluppo di un'appropriata DOCUMENTAZIONE DI COLLAUDO.

C'è tutto? Certamento no... ma c'è abbastanza.

E TUTTO QUESTO PER OGNI SINGOLO PRODOTTO!

Ma se invece di un prodotto software dobbiamo documentare un video-registratore?
In tal caso l'INSTALLATION MANUAL e la QUICK START GUIDE dovrebbero essere sufficenti, almeno per iniziare ad usare il prodotto. Ma deve essere predisposto anche lo USER MANUAL per i clienti più esigenti, che vogliono indagare anche le funzionalità meno comuni.

L'altra settimana ho comprato una piscina di plastica da giardino... di quelle per far giocare i bambini nei giorni più torridi dell'estate; c'era il MANUALE DI MONTAGGIO in forma cartacea ed un CD ROM contenente un filmato di presentazione in formato AVI, in cui sono illustrate
accuratamente tutte le fasi di montaggio e manutenzione.

Insomma, ogni prodotto richiede un set di documenti ben preciso, in base alla sua natura, all'uso che se ne deve fare e a chi lo dovrà utilizzare.

E' ASSOLUTAMENTE NECESSARIO STABILIRE CON ATTENZIONE la manualistica da realizzare per ogni prodotto, nelle diverse forme possibili.

E QUANDO REALIZZIAMO UN PROGETTO PER UN CERTO CLIENTE?

Un progetto si sviluppa attraverso diverse fasi ben distinte; generalmente, ogni fase prevede un certo tipo di documentazione.
Ad esempio, nella fase iniziale di un progetto software, viene redatto il DOCUMENTO DI ASSESSMENT, in cui viene delineata l'analisi del progetto e le soluzioni funzionali richieste, sulla base delle specifiche caratteristiche tecniche e delle logiche di business proprie del cliente,
nonchè di altri vincoli in essere (moduli software/hardware già posseduti dal cliente, prescrizioni legislative, ecc...).

Nella fase finale del progetto, quando l'architettura software viene rilasciata in esercizio, viene prodotto il MANUALE DI ESERCIBILITA', che racchiude tutte le informazioni tecniche necessarie alla gestione dell'architettura.

Se l'architettura prevede l'integrazione di uno più prodotti, dovrà essere rilasciata tutta la necessaria documentazione relativa ad ogni singolo prodotto e l'eventuale sopracitato INTEGRATION MANUAL.

Se poi sono state introdotte delle personalizzazioni "ad-hoc", anche tali moduli personalizzati dovranno essere documentati con manuali dedicati.

Il DOCUMENTO DI ASSESSMENT e il MANUALE DI ESERCIBILITA' possono essere idealmente considerati il documento iniziale e il documento finale di un progetto sofware; lungo lo sviluppo del progetto potranno poi essere rilasciati un gran numero di documenti intermedi.

Analoghe considerazioni possono essere svolte in altri ambiti tecnici.

La DOCUMENTAZIONE DI PROGETTO riveste una sua specificità ed è ancor meno schematizzabile rispetto a quella che dobbiamo sviluppare per un prodotto. La stretta collaborazione tra i diversi progettisti ed il TW, nonchè l'esperienza di tali soggetti nella gestione delle diverse fasi del progetto, sono elementi essenziali per poter sviluppare dei buoni documenti.

In conclusione, spero di avervi convinto, pur non potendo esaurire l'argomento in un singolo post, che la capacità di pianificare COSA si deve fare, PRIMA DI INIZIARE "A FARE", rappresenta il fidato "filo di Arianna" che ci garantisce di non perderci nel labirinto.
Leggi questo articolo...

domenica 12 luglio 2009

14 Luglio Sciopero dei Blogger contro il DDL Alfano

scaricaillogobanner

L'artigiano di Babele aderisce alla protesta dei blogger organizzata da Diritto alla Rete contro il DDL Alfano.

Non è nostra intenzione inserire argomenti di politica in questo forum, ma non condividiamo questo decreto che consideriamo pericoloso per la libertà di espressione.

Ricordiamo che L'artigiano di Babele, NON E’ UNA TESTATA GIORNALISTICA, in quanto viene aggiornato senza alcuna periodicità. Non può pertanto considerarsi un prodotto editoriale ai sensi della legge n. 62 del 7.03.2001, ma il decreto non si rivolge solo alle testate giornalistiche ma a qualsiasi sito informatico.

Le perplessità che abbiamo riguardano l’obbligo di rettifica entro le 48 ore dalla richiesta di un’eventuale soggetto offeso dalle dichiarazioni pubblicate da un sito informatico:

Art. 15.
(…) «Per le trasmissioni radiofoniche o televisive, le dichiarazioni o
le rettifiche sono effettuate ai sensi dell’articolo 32 del testo
unico della radiotelevisione, di cui al decreto legislativo 31 luglio
2005, n. 177.
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»;

Per come è stato scritto, darebbe modo a chiunque non fosse d’accordo con una frase o un post di richiedere la rettifica, vanificando così il pensiero dell’autore.

Se non vi sarà una rettifica, una smentita sul sito, il gestore o il proprietario dello stesso pagherà una multa che può arrivare fino a circa 13.000 euro. Questo vale non solo per i blogger, ma anche per i forum e quindi anche per i post che i lettori inviano.

Benchè in questo sito non esprimiamo pareri negativi su aziende o persone, il decreto ci sembra comunque pericoloso per la libertà di pensiero, in generale, anche per gli altri blogger.

Le leggi sulla diffamazione esistono già ma è sempre un giudice a garantire che quanto dice il presunto offeso sia reale o semplice voglia di creare danno o “chiudere la bocca” ad un’altra persona.

Il 14 Luglio vi sarà una manifestazione a Roma, in Piazza Navona, con i Blogger imbavagliati per una protesta pacifica.

Leggi questo articolo...

sabato 4 luglio 2009

Una perla dal blog di Luisa Carrada

Oggi un post breve breve per segnalarvi una "perla", molto attinente alle problematiche di cui mi occupo.
Lo trovate su http://mestierediscrivere.splinder.com, in data 1° Luglio 2009.

Questo blog è un "luogo delle delizie" per chi si interessa di scrittura professionale e affini e l'ho già segnalato nella categoria DA VISITARE, che trovate in questa pagina, in basso a destra.

Luisa Carrada è una "guru" in questo campo e nel mio percorso da autodidatta, ho imparato molto "saccheggiando" i suoi suggerimenti.
Pur non conoscendola di persona, ho avuto modo di ringraziarla via mail per tutto quello che mi ha insegnato indirettamente, attraverso la lettura dei suoi post e la biblioteca dei "quaderni".

C'è molto da imparare... approfittatene. Leggi questo articolo...

giovedì 2 luglio 2009

Pianificare la produzione della documentazione

Uno degli errori più grossolani che si possono commettere nella produzione della documentazione aziendale, consiste nel NON PIANIFICARE tutte le fasi del processo di produzione. Se siete chiamati sporadicamente a realizzare un documento, potete anche pensare di dare fondo al vostro talento con tutto il corredo di estemporaneità che può derivarne. Ma il talento è nulla senza la tecnica e la capacità di pianificare in ogni aspetto tale processo di produzione. Questo aspetto diviene via via più decisivo in proporzione diretta alla quantità e alla qualità dei documenti che siete chiamati a produrre.

Come sempre, non esiste uno schema universale ed esaustivo che possa andar bene per ogni azienda o contesto professionale.

Esistono però dei passaggi chiave che devono essere sempre tenuti ben presenti e che possono trovare una valida applicabilità nella gran parte delle situazioni.

L'elenco che vi propongo identifica un "set minimo" di attività che può essere arricchito in base alle vostre esigenze:

DEFINIRE UN'ELENCO DI DOCUMENTI CHE ACCOMPAGNANO OGNI PRODOTTO

DEFINIRE UN INSIEME DI TEMPLATE PER OGNI TIPO DOCUMENTO


DEFINIRE UNA CONVENZIONE DI FILE-NAMING PER LA DOCUMENTAZIONE


INDIVIDUARE IL REPOSITORY DELLA DOCUMENTAZIONE AZIENDALE


ORGANIZZARE LA DOCUMENTAZIONE NEL REPOSITORY PRESCELTO


DEFINIRE I CRITERI DI ACCESSO/DISTRIBUZIONE DELLA DOCUMENTAZIONE

NESSUNO DI TALI PUNTI PUO' ESSERE OMESSO nella pianificazione del processo di produzione della documentazione tecnica di un'azienda.

Ovviamente, non è obbligatorio seguire in modo rigidamente sequenziale i passi sopraindicati.
Come ho già raccontato nel post precedente, quando ho cominciato il mio percorso di TW, ho definito per prima cosa una CONVENZIONE PER IL NAMING della documentazione; avevo una priorità assoluta di classificare quanto era stato prodotto, senza alcuna pianificazione, nei precedenti 4 anni e questa prima scelta mi ha facilitato molto il lavoro.

Invece, la definizione dei TEMPLATE è stato un processo progressivo e stratificato, sviluppato per approssimazioni successive e ancora oggi è ben lungi dall'essere terminato.

Nei prossimi post mi riprometto di approfondire i dettagli che mi sembrano più interessanti, inerenti al "set minimo" che vi ho segnalato.
Leggi questo articolo...

domenica 21 giugno 2009

Regole di Naming per la documentazione

Quando nel 2005 iniziai il mio lavoro, per prima cosa dovetti classificare centinaia di documenti realizzati in azienda, all'insegna della più completa anarchia, nei precedenti 4 anni.
La casistica disponibile era sorprendente:
  • documenti sostanzialmente identici salvati con nomi diversi
  • documenti notevolmente diversi salvati con lo stesso nome
  • documenti relativi allo stesso prodotto ma concettualmente diversi (la Scheda Tecnica, il Manuale d'Installazione, il Manuale dell'Amministratore,...) anch'essi identificati dallo stesso nome
  • documenti relativi a versioni diverse dello stesso prodotto salvati con nomi "mimetici" rispetto alla versione
  • documenti salvati con nomi assolutamente scorrelati dal contenuto
  • altro ancora... che al sol pensier ancor mi dole il cor...
Il lavoro di classificazione mi ha impegnato per 3 mesi e la prima cosa che ho fatto è stata quella di definire UNA REGOLA DI NAMING.
Non esistono indicazioni univoche su come impostare una regola di Naming della documentazione aziendale. Anche i guru del Technical Writing di matrice anglosassone, forniscono indicazioni assolutamente ragionevoli e ispirate a principi di "buon senso" che ognuno di noi può identificare autonomamente e deve essere in grado di adattare alla propria realtà lavorativa.

IL PRINCIPIO FONDAMENTALE è:
NON SI INIZIA A CLASSIFICARE NULLA SENZA UNA REGOLA DI NAMING.

La regola che ho adottato e che è ancora in vigore, è estremamente semplice e si struttura in questo modo:

ACRONIMO PRODOTTO/PROGETTO-VERSIONE PRODOTTO/PROGETTO-NOME MANUALE-VERSIONE DOCUMENTO-NOME AZIENDA/CLIENTE

Vediamo due esempi:

NMM-210-Installation_Manual-100-EngNetServices.pdf
Questo nome indica l' Installation Manual del prodotto Network Monitoring Module (NMM), giunto alla versione 2.1.0; la versione del documento è la 1.0.0 e il nome dell'azienda che lo produce è EngNetServices.

PPWC-340-Administration_Manual-120-ENELERGSUN.doc
Questo nome indica l'Administration Manual del prodotto Profile Provisioning Web Console (PPWC), sviluppato per il cliente ENELERGSUN, giunto alla versione 3.4.0; la versione del documento è la 1.2.0.

Come vedete, non è necessaria un'intelligenza cartesiana per definire una regola di Naming.

Tipicamente, ne fanno uso le aziende di alto livello e ben organizzate, in cui la produzione e la classificazione della documentazione rappresenta un'elemento importante della filosofia di business.
In particolare, le aziende che si sottopongono ad un percorso di certificazione di qualità dei processi produttivi, adottano regole di Naming anche molto più articolate di quella che ho adottato io.

Ovviamente questa regola non è la migliore possibile ma funziona abbastanza bene.
In questo modo i nomi apposti ai documenti divengono "parlanti", nel senso appena illustrato.

L'efficacia di una regola di Naming dipende anche dal contesto.
L'ACRONIMO PRODOTTO/PROGETTO ha più senso in un'ottica "interna" che esterna.
Quindi questa regola va benissimo per la documentazione tecnica, molto meno per la documentazione di Marketing, dove anche il nome del documento deve, in genere, essere più "esplicito".
Nulla vieta di adottare 2 o 3 regole di Naming distinte, all'interno dell'azienda, purchè siano ben specificate e note a tutti gli appartenenti della medesima.
Io preferisco una regola unica, semplice e flessibile quanto basta.

Ma ovviamente e come sempre, non si può avere tutto dalla vita; in quest'ottica vediamo in che modo si potrebbe modificare la regola illustrata se volessimo ottenere nomi "più compatti" (ma meno "parlanti").

Immaginiamo di assegnare un codice numerico a tutte le tipologie di documentazione previste per un generico prodotto:

001 - Technical Specification
002 - Installation Manual
003 - Getting Started Manual
004 - Administration Manual
005 - Product Manual
006 - Developer Manual

Riprendiamo gli esempi precedenti:

NMM-210-Installation_Manual-100-EngNetServices.pdf
NMM-210-002-100-EngNetServices.pdf

PPWC-340-Administration_Manual-120-ENELERGSUN.doc
PPWC-340-004-120-ENELERGSUN.doc

Come vedete, la regola induce a nomi più compatti ma meno intellegibili.

Ovviamente, una regola di Naming può essere utile anche per classificare i vostri documenti privati.

Come sempre, vi sottopongo la mia esperienza senza la pretesa di proporre formule esaustive, ma con l'intenzione di fornirvi spunti utili per una migliore gestione della documentazione.
Usate le regole di Naming... ne trarrete solo vantaggi.
Leggi questo articolo...

giovedì 11 giugno 2009

Contenuti di una pagina Web: la regola "F shape"

Alcuni giorni orsono la mia fidata collega Claudia, che mi aiuta nella realizzazione della documentazione aziendale, mi segnalava la sua difficoltà nel documentare una specifica funzionalità di una Web Console per l'amministrazione di uno dei nostri prodotti.
Ci mettiamo insieme a guardare il problema... e continuiamo a non vederlo.

Sarà la stanchezza del fine giornata ? Dopo un pò di tempo (diciamo un pò troppo...) ci accorgiamo della label identificativa di un accordion pane posizionato in basso a destra... di colore celeste su sfondo chiaro!

Eppure nei nostri prodotti questo elemento grafico viene usato con una certa frequenza... perchè stavolta non lo avevamo visto?
Dopo un breve smarrimento mi è ritornata in mente una delle lezioni più famose di Jacob Nielsen, il guru riconosciuto della Web "usability" e della comunicazione efficace dei contenuti Web.


La figura precedente la trovate sul suo sito www.useit.com, che vi invito a visitare e saccheggiare... intellettualmente parlando.
La figura rappresenta ciò che io chiamo la "densità di sguardo", cioè la tendenza a posizionare gli occhi di un lettore di una pagina Web prevalentemente su certe zone della pagina rispetto ad altre.
Le zone rosse sono quelle dove gli occhi del lettore tendono a posizionarsi più frequentemente; via via, la frequenza diminuisce virando dal rosso al giallo, al blù fino al grigio.
Tale ricerca ha suggerito che sia conveniente "addensare" i contenuti significativi di una pagina Web nella zona alto-centrale-sinistra, perchè è in quella zona che, prevalentemente, andiamo con lo sguardo a cercare le informazioni.

Quando scriviamo per il Web o progettiamo applicazioni Web, questa è una delle regole auree che bisognerebbe sempre osservare.

Quindi, se poi alle ore 19 ci si ritrova con un elemento grafico CELESTE... SU SFONDO CHIARO... IN BASSO A DESTRA... se proprio non lo si vede al primo colpo... siamo, almeno in parte, giustificati!
Leggi questo articolo...