Manuali tecnici: perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti?

Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel. / Fax: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
Perché passare dalla scrittura “free style”
alla gestione strutturata dei contenuti?
Punti di debolezza della documentazione tecnica, cresciuti bisogni informativi dei
destinatari, normative, standard e best practices: viaggio alla scoperta di motivi e
metodi per strutturare i contenuti e adottare con successo sistemi CMS (Content
Management Systems)
Sommario
Premessa............................................................................................................................................................................ 2
I vincoli del “free style” ........................................................................................................................................................ 2
Punti di debolezza della documentazione tecnica “free style” ......................................................................................... 2
Bisogni informativi dei destinatari della comunicazione tecnica....................................................................................... 3
Normativa, standard e best practices .............................................................................................................................. 4
Vantaggi della gestione strutturata dei contenuti e dell’adozione di CMS ........................................................................... 5
La tecnologia da sola non basta.......................................................................................................................................... 7
Conclusione ........................................................................................................................................................................ 8
1
Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS

Tel. / Fax: +39 045 6152381
Premessa
K. Halvorson e M. Rech (Content Strategy per il web. I
contenuti fanno la differenza, Pearson, Milano, Torino, 2013,
p. 122) riportano un’interessante citazione dell’esperta di
content strategy Karen McGrane:
… dobbiamo iniziare a pensare ai contenuti come a
qualcosa, che vive a prescindere dalle piattaforme di
pubblicazione. Non possiamo immaginare l'aspetto dei
contenuti in uno specifico documento, in una pagina o in una
schermata. Dobbiamo invece strutturare i contenuti per
poterli riusare.
Ora, il contenuto strutturato non è una novità, ma è sempre
stato posizionato come un problema di tecnologia ... Ma non
si tratta di un problema di tecnologia: è un problema di
strategia. Quali sono gli oggetti contenuto essenziali con cui
abbiamo a che fare? Quali metadati ci servono per
organizzarli in modo efficace? Quali sono le regole a essi
dedicate nel nostro settore?
Se non riusciamo a rispondere a queste domande … dispositivi e piattaforme del futuro ci prenderanno in contropiede.
Dobbiamo iniziare … a separare del tutto contenuto e forma.
La citazione è a effetto, ma quali sono i criteri che ci permettono di capire, se nella nostra azienda è giunto il momento di
abbandonare la scrittura “free style”, ovvero la realizzazione manuale dei documenti, e avviare un progetto di gestione
strutturata dei contenuti utilizzati nel complesso della documentazione tecnica (manuali, guide rapide, help online,
cataloghi, schede, listini, ecc.)?
Analizzare i punti di debolezza della documentazione tecnica, i bisogni informativi dei destinatari, le normative, gli
standard e le best practices di settore ci aiuta a rispondere a questa domanda, che rappresenta la prima tappa del nostro
viaggio.
I vincoli del “free style”
Punti di debolezza della documentazione tecnica “free style”
L’aumento della complessità della documentazione tecnica è il fattore che, più di ogni altro, evidenzia i limiti della
scrittura “free style”.
Gestire i contenuti all’interno della pagina o della videata dei singoli documenti rende di per sé difficile:
 Far collaborare più figure professionali
 Aggiornare in modo certo contenuti presenti in più
documenti
 Garantire la coerenza dell’informazione, cioè – per
esempio – il fatto che denominazione e descrizione della
macchina corrispondano nella scheda tecnica allegata
all’offerta e nella successiva fattura
 Standardizzare e riutilizzare i contenuti
 Utilizzare glossari e terminologie
2

Tel. / Fax: +39 045 6152381
 Contenere i costi di traduzione, poiché le informazioni di partenza non sono standardizzate e univoche, né è agevole
individuare e riutilizzare traduzioni già esistenti
 Omogeneizzare presentazione e formattazione dei contenuti
 Realizzare pubblicazioni multicanale (su carta, cd/dvd/usb, web, mobile, app, ecc.) e mirate a singoli destinatari
(personale interno all’azienda, forza vendita, rivenditori e partner, installatori, utilizzatori, manutentori e assistenza
tecnica, ecc.)
 Integrare i contenuti presenti nelle varie fonti dati aziendali (sistemi gestionali, software ERP, MRP, CAD, PDM,
CMS, ecc.).
Una semplice simulazione ci aiuta a capire come, all’aumento della complessità della documentazione tecnica, la
scrittura “free style” finisca per rappresentare un fattore di inefficienza.
Immaginiamo che in origine un’azienda tipo producesse 1 sola macchina, dedicata al mercato nazionale, per cui era
sufficiente realizzare manualmente, con MS Word, 1 manuale in italiano.
L’azienda ha poi iniziato a produrre la macchina in 6 modelli diversi. Ogni modifica a un contenuto comune ai manuali
andava quindi replicata su 1 + 6 file di Word.
Per ottemperare alla Direttiva Macchine, l’azienda ha scorporato il manuale per l’installatore / manutentore da quello per
l’utilizzatore, creando 2 versioni per ogni manuale e ottenendo 1+6+12= 19 documenti di Word da manutenere.
Per rispondere alle richieste degli utenti, l’azienda ha poi deciso di affiancare a ogni manuale una guida rapida, portando
a 1+6+12+12 = 31 1 documenti di Word.
Infine, l’azienda ha iniziato a espandersi all’estero, il che ha richiesto la traduzione in 3 lingue di manuali e guide rapide.
Il risultato è stato di 31 x 4 = 124 documenti di Word.
La storia potrebbe continuare, includendo – per esempio – l’esigenza di pubblicare online la documentazione tecnica, di
personalizzarla graficamente per i rivenditori primari, di realizzare cataloghi ricambi, ecc.: l’aggiunta di gradi di
complessità farebbe aumentare inesorabilmente il numero di documenti di Word da manutenere, e con esso tempi, costi
e rischi di disallineamento.
Compiendo un balzo in avanti, immaginiamo che l’azienda sia passata dalla scrittura “free style” alla gestione strutturata
dei contenuti, adottando anche un software CMS (Content Management System).
Standardizzazione, univocità e riutilizzo dei contenuti supportati dal software CMS fanno sì che ogni modifica a un
contenuto comune vada apportata in un solo punto (1 modifica nella prima lingua + 3 traduzioni) e sia poi propagata in
automatico a tutti i 124 documenti.
L’efficienza è evidente, in termini di risparmio di tempi e costi, nonché di certezza del risultato.
Bisogni informativi dei destinatari della comunicazione tecnica
Oltre ai bisogni informativi primari, alcuni fattori – quali
l’incremento della complessità dei macchinari, la contrazione
del tempo dedicato alla formazione, l’avvento del mobile,
ovvero della possibilità di usufruire di contenuti in rete tramite
dispositivi mobili (smartphone, tablet, ecc.) – fanno sorgere
nuovi bisogni informativi nei destinatari della comunicazione.
Fra i bisogni informativi primari annoveriamo l’esigenza di
disporre di contenuti:
 Corretti, aggiornati e coerenti all’interno di tutti i
documenti che accompagnano il ciclo di vita della macchina
(dalla proposta commerciale, all’installazione e formazione
presso il cliente, alla fatturazione, alla gestione della
ricambistica, ecc.)
 Di facile comprensione
3

Tel. / Fax: +39 045 6152381
 Localizzati nella lingua del fruitore.
I bisogni informativi emergenti sono invece rappresentati dall’esigenza di disporre di contenuti:
 Basati su immagini e video, per facilitare la comprensione della sequenza delle operazioni da svolgere
 Ricercabili
 Contestuali, cioè consultabili nel posto giusto e nel momento giusto, superando il gap attuale, per cui i contenuti si
collocano spesso altrove rispetto ai luoghi e ai tempi in cui sono effettivamente necessari
 Targetizzati per il profilo del fruitore, in modo tale da limitare il sovraccarico informativo
 Corredati da strumenti di condivisione di problemi e soluzioni
 Integrati e aggregati, in modo tale da non dover consultare separatamente più fonti per raccogliere i dati necessari.
Dal momento che le informazioni sono parte integrante del prodotto, il fatto di rispondere non solo ai bisogni informativi
primari, ma anche a quelli emergenti, equivale a conferire un vantaggio competitivo al prodotto.
Si tratta quindi di un tassello importante nella strategia aziendale. Un tassello, che implica la moltiplicazione dei canali
utilizzati e dei tipi di pubblicazione editi dall’azienda. Una moltiplicazione, che – come abbiamo visto in precedenza – la
scrittura “free style”, a causa della sua manualità, non supporta in modo efficiente ed efficace.
Attualmente il canale web e mobile è quello che catalizza la maggiore attenzione, poiché particolarmente adatto a
realizzare e veicolare tipi di pubblicazione e funzioni in grado di rispondere ai bisogni informativi emergenti:
 Gallerie di immagini, video, modelli navigabili in 2D/3D, eventualmente collegati al catalogo ricambi
 Strumenti per la ricerca e il filtraggio delle informazioni
 Fornitura di informazioni contestuali, grazie a strumenti in grado di stabilire un collegamento fra l’ambiente reale in
cui opera l’utente e i contenuti disponibili. Per esempio, integrando l'apposizione di codici QR (Quick Read) su parti
della macchina con la realizzazione e la pubblicazione online di documentazione mirata, gli utenti possono
consultare da dispositivi mobili informazioni contestuali:
 Istruzioni
 Indicazioni di parti di ricambio
 Avvisi (segnalazioni provenienti da knowledge base o forum; indicazione dei dispositivi di protezione individuali
[DPI] da indossare, ecc.)
 FAQ, knowledge base, blog e forum per la collaborazione degli utenti fra loro e con l’azienda
 Applicazioni per la visualizzazione integrata e aggregata di contenuti, targetizzati in modo automatico in base al
profilo dell’utente.
Nell’approccio “free style” la realizzazione di questo tipo di pubblicazioni e funzioni è estremamente onerosa, se non
impossibile.
Partendo invece da una gestione strutturata dei contenuti e da software CMS predisposti per alimentare in modo
automatico applicazioni web e mobile, la realizzazione di questo tipo di pubblicazioni e funzioni diventa una strada
percorribile agevolmente per aggiungere valore al patrimonio informativo aziendale, incrementandone la redditività, e per
conferire al prodotto un vantaggio competitivo.
Normativa, standard e best practices
Nell’ambito della redazione di manuali e di istruzioni d’uso la
normativa di riferimento è vasta.
Senza pretesa di completezza, le norme internazionali e
nazionali da considerare sono:
 Direttiva Macchine 2006/42/CE recepita a livello
nazionale dal D. Lgs. 17/2010
 Norme armonizzate 12100:2010 Sicurezza del
macchinario - Principi generali di progettazione - Valutazione
del rischio e riduzione del rischio: la norma regolamenta
4

Tel. / Fax: +39 045 6152381
anche le istruzioni d'uso e rinvia alla norma internazionale IEC 62079 recepita a livello europeo dalla norma EN
62079, sostituita dalla IEC 82079-1:20129
 ISO IEC 82079-1:2012 Preparation of instructions for use - Structuring, content and presentation - Part 1: General
principles and detailed requirements
 UNI 10653:2003 "Qualità della documentazione tecnica di prodotto"
 UNI 10893:2000 "Documentazione tecnica di prodotto. Articolazione e ordine espositivo del contenuto"
 UNI/TS 11192:2006 "Documentazione tecnica di prodotto destinata all'utente. Criteri per la classificazione".
Alle normative si aggiungono poi:
 Standard di settore, come l’AECMA / ATA / S1000D per il settore aeronautico e militare
 Standard indipendenti, come il DITA (Darwin Information Typing Architecture) di OASIS (Organization for the
Advancement of Structured Information Standards) per le applicazioni di e-business
 Best practices della scrittura tecnica (technical writing).
Norme, standard e best practices hanno l’obiettivo di migliorare la qualità dei contenuti, nonché dei processi di
redazione, traduzione, pubblicazione e distribuzione della documentazione tecnica, regolando il flusso di lavoro, la
struttura, l’ordine espositivo e il contenuto delle informazioni, le regole semantiche della comunicazione, la presentazione
grafica, il formato dei file, ecc.
Anche nella traduzione pratica di questi aspetti la scrittura “free style” fatica. Pensiamo solo a un contenuto
apparentemente semplice come il warning. La normativa richiede, che ogni warning comprenda un pittogramma,
l’etichetta relativa al tipo di warning (nota, attenzione, pericolo, divieto, ecc.), l’illustrazione della causa, delle
conseguenze e dei rimedi. Gestendo a mano i contenuti, l’operatore deve ricordare e applicare la struttura prevista,
impaginare il pittogramma e attribuire a ogni contenuto lo stile corretto.
La gestione mediata da CMS permette invece di definire e applicare in automatico la struttura prevista, di aggiungere in
automatico il pittogramma e di esportare nei vari formati di file lo stesso contenuto, utilizzando in particolare tecnologie
XML per trasformarlo nelle standard di destinazione(per esempio il DITA).
Vantaggi della gestione strutturata dei contenuti e dell’adozione di CMS
Nella seconda tappa del nostro viaggio analizzeremo il modo in cui la gestione strutturata dei contenuti e l’adozione di
software specifici (CMS, sistemi di editing, authoring tool, sistemi di impaginazione automatica, ecc.) possano aiutarci a
superare le debolezze della scrittura “free style”, a rispondere ai bisogni informativi dei destinatari, a recepire norme,
standard e best practices, ovvero non solo a rendere efficiente la gestione dei contenuti, ma anche a incrementarne il
rendimento pubblicandoli e diffondendoli in modo efficace.
Obiettivo è mettere a frutto il patrimonio informativo aziendale sia per migliorare il trasferimento della conoscenza dei
prodotti e del loro utilizzo, sia per ampliare la gamma dei servizi di supporto offerti alla forza vendita, all’assistenza
tecnica e agli utilizzatori.
Le caratteristiche che prenderemo in esame si riferiscono ad Argo CMS, il software di KEA s.r.l. dedicato alla gestione
collaborativa di contenuti multilingua e alla produzione automatizzata di documentazione tecnica multicanale.
Gestire i contenuti in modo strutturato, utilizzando un software CMS, comporta vantaggi così sintetizzabili:
5

Tel. / Fax: +39 045 6152381
 Gestione collaborativa dei contenuti
 Grazie alla gestione delle autorizzazioni, il CMS permette a varie figure professionali, interne ed esterne
all’azienda (product manager, technical writer, traduttori, consulenti, ecc.), di collaborare all’editing dei contenuti
in base a flussi di lavoro codificati
 Gestione univoca dei contenuti riutilizzabili e delle loro revisioni
 Il CMS permette di gestire in modo univoco contenuti riutilizzabili a qualsiasi livello, dal macro al micro: capitoli,
warning, termini tratti da glossari, variabili, ecc.
 Revisionando un contenuto comune, la modifica può essere o meno propagata in modo automatico alle sue
istanze presenti nei vari documenti
 Supporto di glossari e terminologie
 Definizione e applicazione di strutture di contenuti (modelli, template) riutilizzabili, per esempio dei warning sopra
citati
 Gestione delle traduzioni
 Attraverso un sistema di marcatura, il CMS permette di sottoporre al traduttore solo i contenuti da tradurre o da
rivedere, ottimizzando i costi
 Le traduzioni, eseguibili mediante software di traduzione assistita (CAT Tool, come SDL Trados, WordFast,
ecc.), sono importate in modo automatico nel CMS. Ciò fa risparmiare tempo e garantisce la precisa
corrispondenza fra testo originale e traduzione, svincolata dalle competenze linguistiche del technical writer
 Marcatura dei contenuti finalizzata al riutilizzo
 La marcatura o classificazione a faccette assegna "a un oggetto caratteristiche multiple (attributi), consentendo
di ordinare e filtrare le informazioni da molteplici punti di vista, anziché in base a un unico schema predefinito,
tassonomico. Una faccetta comprende attributi … chiaramente definiti, mutuamente esclusivi e
complessivamente esaustivi. Per esempio un insieme di libri può essere classificato utilizzando una faccetta per
l'attributo Autore, una per l'attributo Soggetto, una per l'attributo Data, ecc." (Wikipedia). Attraverso la marcatura
il technical writer definisce l’ambito di utilizzo di un contenuto comune, cioè – per esempio – a quale famiglia,
modello, macchina, codice della distinta base (BOM – Bill of Material) si riferisce, qual è il suo destinatario, per
quali tipi di pubblicazione è stato concepito, attraverso quali canali può essere veicolato, ecc.
 Sulla marcatura si basa, per esempio, il funzionamento dei configuratori della documentazione tecnica e la
produzione automatica di documenti targetizzati
 Automazione nella produzione dei vari tipi di documentazione tecnica, targetizzati per i vari destinatari, da veicolare
attraverso i vari canali
 Grazie all’integrazione con software di impaginazione automatica e con applicazioni web, il CMS permette di
automatizzare le funzioni di cross media publishing. I vantaggi sono il risparmio di tempi e costi, la correttezza
dei contenuti, la possibilità di targetizzare le informazioni, nonché la coerenza nell’applicazione degli stilemi
grafici
 Il CMS permette anche di alimentare piattaforme di e-commerce, dedicate per esempio alla vendita di ricambi.
Si tratta di un’opportunità interessante per trasformare in fonte di guadagno la gestione della documentazione
tecnica, che in alcune realtà è ancora percepita soprattutto come fattore di costo
 Integrazione
 Il CMS spesso condivide dati (classificazioni, codici, prezzi, disegni, ecc.) con altri strumenti informatici presenti
in azienda: sistemi gestionali, ERP, MRP, PLM, CAD, CMS web, ecc. Integrare il CMS nell’ecosistema
informativo è vantaggioso, poiché permette alle varie aree aziendali di condividere informazioni corrette, di
utilizzarle per redigere i documenti che accompagnano ciclo di vita della macchina, nonché di fornire
informazioni aggregate, senza costringere gli utenti a consultare varie fonti per raccogliere i dati di cui
necessitano.
6

Tel. / Fax: +39 045 6152381
La tecnologia da sola non basta
La terza e ultima tappa del nostro viaggio si sofferma sulla
centralità dell’opera di alfabetizzazione e formazione delle
persone, che – a vario titolo – sono chiamate a realizzare,
gestire e utilizzare contenuti strutturati.
Il successo del passaggio dalla scrittura “free style” alla
gestione strutturata dei contenuti dipende non soltanto dalle
scelte tecnologiche, ma anzitutto dalla comprensione,
condivisione e applicazione di scelte metodologiche.
Questo, perché l’obiettivo comune alle attività fin qui illustrate
è di produrre contenuti "certificati", riutilizzabili all'interno della
documentazione tecnica aziendale, comunicata a vari
destinatari, attraverso vari canali e tipi di pubblicazione.
Riutilizzare per migliorare la qualità della comunicazione e
per incrementare il rendimento dell'investimento necessario
alla produzione e traduzione delle informazioni.
Nella nostra esperienza vi sono vari fattori metodologici, che concorrono al buon esito di un progetto di gestione
strutturata dei contenuti e di adozione di software CMS. Eccoli in dettaglio:
 Standardizzazione
 Standardizzare i contenuti significa esprimere in modo uguale concetti uguali. In fase di migrazione dei
contenuti verso software CMS la standardizzazione è fondamentale, poiché permette di scrivere e tradurre una
sola volta un’informazione, migliorando l'efficienza della redazione (editing) e della traduzione, e rendendo
coerente la comunicazione
 La standardizzazione include anche l’applicazione di regole e standard della scrittura tecnica (technical writing)
 Univocità
 Per rendere efficienti redazione e traduzione, ogni contenuto deve essere univoco: va gestito cioè una sola
volta nel sistema e riutilizzato laddove necessario. Nel software CMS ogni frammento di contenuto (snippet)
segue il proprio ciclo di vita e può essere presente in una o più revisioni, ognuna delle quali utilizzata in una o
più pubblicazioni. L'univocità è la chiave per modificare l’informazione in un solo punto e propagare in modo
certo la modifica a tutte le istanze
 Granularità
 Un punto di forza dei sistemi di gestione dei contenuti sta nella loro capacità di agevolare il riutilizzo delle
informazioni. Per riutilizzare un contenuto è necessario, che esso sia disponibile a un livello di granularità
adeguato. Per esempio:
 Se il capitolo di presentazione della tavola dei pittogrammi va sempre riutilizzato in toto, può essere gestito
a un basso livello di granularità, cioè come un unico blocco, composto da una serie di paragrafi, che
saranno riutilizzati sempre tutti insieme
 Nel caso dei warning, che vanno utilizzati singolarmente, è invece necessario granularizzare maggiormente
i contenuti
 Il massimo grado di granularizzazione va riservato infine a termini del glossario e a dati variabili
(denominazioni di famiglia, modello o macchina, codice matricola, ecc.), che sono inseriti in-line, cioè nel
flusso del testo di paragrafi presenti in uno o più documenti
 Classificazione e marcatura
 Per riutilizzare i contenuti è necessario che il technical writer riesca a trovare facilmente l'informazione cercata e
a comprendere in quale ambito un determinato contenuto possa essere utilizzato. Sono fondamentali in questo
senso un sistema di classificazione condiviso e funzioni di filtraggio delle informazioni basate sulle marcature
apportate.
7

Tel. / Fax: +39 045 6152381
Conclusione
Se ci sono aspetti in cui vi riconoscete e pensate possa essere opportuno ipotizzare l’avvio di
un progetto di gestione strutturata dei contenuti, siamo a vostra disposizione per un’analisi
gratuita della documentazione tecnica e dei vostri flussi di lavoro attuali, e per provare dal
vivo il nostro software Argo CMS.
Contattateci a info@keanet.it o al numero di telefono +39 045 6152381!
Autore: Petra Dal Santo
Petra Dal Santo è fondatrice e socia di KEA s.r.l., dove si occupa di project management nell’ambito
di progetti legati all’adozione di software CMS, all’impaginazione automatica, nonché allo sviluppo di applicazioni web e
mobile. E’ autrice del blog di KEA, dedicato ai temi della comunicazione e documentazione tecnica.
E-mail: dalsanto@keanet.it
Sito: http://www.keanet.it
Blog: http://blog.keanet.it/
8

Manuali tecnici: perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti?

Recommandé

Recommandé

Contenu connexe

Plus de KEA s.r.l.

Plus de KEA s.r.l. (20)

Manuali tecnici: perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti?