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...
sabato 17 ottobre 2009
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...
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.
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:
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...
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
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...
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:
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...
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
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!
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...
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...
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...
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.
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...
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...
Iscriviti a:
Post (Atom)
