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

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

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

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

La documentazione tecnica come moltiplicatore di business revenues

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

Leggi questo articolo...

La Qualità non è un pranzo di gala.

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

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

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

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

In particolare vi invito a leggere i post del:

• 10-01-2009

• 25-02-2009

• 15-12-2009

Quello che mi preme sottolineare è che:

• la ricerca della Qualità è un PROCESSO e come tale può essere studiato e ingegnerizzato;

• la Qualità non è mai gratis, ma richiede un lavoro;

• la Qualità è un "TUTTO" che molto spesso non riusciamo ad ottenere completamente ma a volte, con opportune strategie, possiamo ottenere almeno "UNA PARTE DEL TUTTO" e sarà comunque meglio del "NULLA".

Leggi questo articolo...

La Qualità della documentazione tecnica: Chiarezza e Sintesi

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

Lo Zen e la Qualità della documentazione tecnica

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

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

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

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

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

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

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

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

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

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

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

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

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

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


ERRORE n° 5: contenuti non interessanti!

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

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

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

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

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


ERRORE n° 6: non utilizzare una struttura chiara!

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

- SOMMARIO (1 pagina)
- INTRODUZIONE (1 pagina)
- DEFINIZIONE DEL PROBLEMA (2 pagine)
- ILLUSTRAZIONE DELLA SOLUZIONE (2 pagine)
- CASE STUDY (opzionale, 1 pagina)
- CONCLUSIONI (1 pagina)

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

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


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

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

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

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

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


ERRORE n° 8: sbagliare la chiusura!

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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


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

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

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

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


ERRORE n° 3: sbagliare il titolo!

Sbagliare il titolo può essere un errore senza ritorno!

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

Alcuni trucchi? Almeno 2.

TITOLO E SOTTOTITOLO

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

DITE AL LETTORE CHE COSA OTTERRA’

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

Un esempio?

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

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

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

Io leggerei per primo WP2, e voi?

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

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

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

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

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


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

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

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