Il documento illustra come adottare con successo un software CMS (Content Management System) per realizzare manuali e documentazione tecnica. Si sofferma in particolare su: standardizzazione dei contenuti, univocità nella gestione dei contenuti, livello di granularità dei contenuti, normative di settore, metodiche di technical writing, classificazione gerarchica e a faccette, marcatura e riutilizzo dei contenuti

1. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel. / Fax: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
Come adottare con successo un software CMS (Content
Management System) per realizzare manuali e documentazione
tecnica
Consigli per migrare i contenuti da una gestione “a mano”, non strutturata (effettuata per
esempio utilizzando MS Word), a una gestione strutturata, tramite software di Content
Management
Il modo in cui avviene la migrazione delle informazioni verso il software di gestione dei contenuti rappresenta un
fattore determinante per il successo di un progetto di adozione di un sistema CMS.
Nelle fasi iniziali dei progetti di adozione di Argo CMS, il nostro software per la realizzazione di manuali e
documentazione tecnica, ci sentiamo rivolgere spesso la domanda, se Argo disponga di funzioni di importazione
della documentazione pregressa.
Al di là delle soluzioni tecniche possibili (Argo dispone di funzioni di importazione di testi in formato RTF, DOC e
DOCX e di tabelle in formato XLS, ed è possibile lo sviluppo di funzioni di importazione a progetto), a questa
domanda replichiamo con il quesito: “Sì, ma che cosa intendete importare in Argo?”.
Da una prima, rapida analisi emerge normalmente, che la documentazione pregressa – specie se gestita “a
mano”, in modo non strutturato – non esprime e non traduce in modo uguale concetti uguali: dal macro al micro,
per ogni contenuto (sia esso, per esempio, una tavola di presentazione dei pittogrammi, un warning o l’etichetta
del modello del macchinario) esistono spesso diverse versioni, stratificatesi nel tempo e che necessitano di essere
anzitutto standardizzate prima della loro migrazione all’interno del software di gestione dei contenuti.
Ma la standardizzazione non è tutto.
Nella nostra esperienza, vi sono vari fattori, che concorrono a una migrazione “di qualità” e quindi a porre le basi
per un progetto CMS di successo.
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, perché permette di
scrivere e tradurre una sola volta un determinato contenuto, migliorando l’efficienza della redazione (editing) e
della traduzione, e rendendo coerente la comunicazione.
Univocità
Per rendere efficiente la redazione (editing) e la traduzione, ogni contenuto deve essere univoco, va gestito cioè
una sola volta nel software di content management e riutilizzato laddove necessario.
Naturalmente nel CMS ogni frammento di contenuto (componente) ha un proprio ciclo di vita e può quindi essere
presente in una o più revisioni, ognuna delle quali utilizzata (istanziata) in uno o più manuali, guide, help, schede,
documenti tecnici, ecc.
L’univocità è la chiave per applicare modifiche in un solo punto e riutilizzare in modo certo i contenuti.
1
Come adottare con successo un software CMS (Content Management System) per realizzare manuali e
documentazione tecnica – Febbraio 2013

2. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel. / Fax: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
Granularità
Un punto di forza dei software di gestione dei contenuti sta nella loro capacità di agevolare il riutilizzo delle
informazioni.
I CMS permettono, per esempio, di gestire in modo univo un warning sull’obbligo di dispositivi di protezione
individuali e di utilizzarlo (istanziarlo) in tutti i documenti e in tutti i punti necessari.
Per riutilizzare un contenuto è tuttavia 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 (note, attenzioni, pericoli, divieti, ecc.), invece, che vanno utilizzati singolarmente – per
attirare l’attenzione dell’utente sul corretto comportamento da tenere –, è necessario granularizzare
maggiormente i contenuti
• Il massimo grado di granularizzazione va riservato infine ai dati variabili (per esempio: espressioni tratte dal
glossario aziendale, denominazioni, ecc.), che andranno utilizzati nel flusso del testo (in-line), cioè all’interno
dei paragrafi di uno o più documenti.
Mentre “a mano” è estremamente difficile gestire l’univocità, la granularizzazione e il riutilizzo dei contenuti, i
software CMS mettono a disposizione del redattore tutte le funzioni necessarie a tenere facilmente sotto controllo
questi aspetti.
Standardizzazione, univocità e scelta del livello di granularità rappresentano le linee guida per “distillare” dalla
manualistica e documentazione tecnica pregressa i contenuti da importare all’interno del software di content
management.
Per garantire la qualità dei contenuti da migrare è tuttavia necessario considerare anche altri fattori.
Normative
La migrazione è l’occasione per verificare, se struttura, contenuti e forme di presentazione sono conformi alle
normative vigenti (per esempio alla Direttiva Macchine 2006/42/CE) e per effettuare eventuali adeguamenti.
Metodiche di techical writing
La migrazione è anche l’occasione per rivedere i contenuti applicando regole e standard della scrittura tecnica
(technical writing), che hanno l’obiettivo di ridurre i costi di redazione, manutenzione e traduzione della
documentazione, di garantirne qualità e conformità alle normative, nonché fruibilità ottimale da parte dei
destinatari (per esempio gli installatori, operatori e manutentori di un macchinario).
I software di gestione dei contenuti possono agevolare il redattore proponendo modelli (template) di manuali a
norma, supportando la gestione della terminologia e di glossari personalizzati e fornendo funzioni di
autocompilazione.
In fase di migrazione può essere opportuno, che il redattore sia affiancato da consulenti esperti di normative e di
technical writing, in modo acquisire o perfezionale le relative competenze.
Obiettivo comune a tutte le attività fin qui illustrate è di produrre contenuti “certificati”, riutilizzabili all’interno di tutta
la documentazione tecnica aziendale, comunicata a vari destinatari (per esempio: forza vendita, rivenditori,
installatori, utilizzatori, manutentori, ecc.), attraverso vari canali (carta, web, mobile, app, cd/dvd, ecc.) e format
editoriali (manuali, guide, certificazioni, schede, cataloghi, listini, ecc.).
Riutilizzare i contenuti significa incrementare il rendimento dell'investimento necessario alla loro produzione.
2
Come adottare con successo un software CMS (Content Management System) per realizzare manuali e
documentazione tecnica – Febbraio 2013

3. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel. / Fax: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
Per riutilizzare i contenuti è però necessario che il redattore riesca a trovare facilmente l’informazione cercata e a
comprendere in quale ambito un determinato contenuto possa essere utilizzato (per ambito intendiamo, per
esempio, qual è il suo destinatario, per quali format editoriali è stato concepito, attraverso quali canali può essere
veicolato, ecc.).
I sistemi di classificazione e di configurazione messi a disposizione dai software di content management
rappresentano un aiuto prezioso in questo senso.
Classificazione gerarchica
La classificazione gerarchica rappresenta un primo strumento, che il redattore ha per reperire i contenuti da
riutilizzare.
Per essere intuitivo, e quindi efficace, il sistema di classificazione deve essere standard o comunque condiviso
all’interno della comunità dei suoi fruitori.
I software CMS dispongono comunque normalmente di un motore di ricerca interno, che permette al redattore di
cercare parole o espressione chiave, a prescindere dal sistema con cui i contenuti sono classificati.
Classificazione a faccette e marcatura
Classificazione a faccette e marcatura specificano l’ambito in cui un determinato contenuto (per esempio un intero
capitolo, un singolo warning o una variabile) può essere utilizzato.
Per classificazione a faccette intendiamo “un sistema, che permette di assegnare 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 di una classe o di un soggetto
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.”.
http://en.wikipedia.org/wiki/Faceted_classification
Nel contesto della manualistica, dei cataloghi tecnici e della documentazione tecnica, la classificazione a faccette
è essenziale per:
Definire l’ambito in cui un determinato contenuto può essere utilizzato. L’ambito può essere un destinatario, un
canale di comunicazione, un format editoriale, un codice della distinta base, un modello o una famiglia di
macchinari, ecc.
Alimentare configuratori che permettano al redattore di riprendere facilmente i contenuti corretti in fase di
realizzazione di una pubblicazione e al destinatario della comunicazione di cercare le informazioni in modo
multidimensionale (per esempio in base alla classificazione merceologica del prodotto, alle sue caratteristiche
tecniche, a un guasto, ecc.)
Alimentare in modo automatico applicazioni web (mobile, app, ecc.), dedicate alla fruizione di sottoinsiemi di
contenuti opportunamente marcati (per esempio cataloghi ricambi, guide all’installazione, troubleshooting per la
risoluzione di problemi, ecc.).
Autore: Petra Dal Santo (dalsanto@keanet.it)
www.keanet.it
http://blog.keanet.it/
3
Come adottare con successo un software CMS (Content Management System) per realizzare manuali e
documentazione tecnica – Febbraio 2013