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

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

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

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