Report sul libro di Sissi Closs, Single Source Publishing, Entwickler.Press, Frankfurt a.M., 2011 Il libro di Sissi Closs è dedicato al passaggio dalla "documentazione monolitica" (p. 28 – espressione utilizzata anche da Alessandro Stazi nel suo blog http://artigianodibabele.blogspot.it/) al single sourcing e al single source publishing. Secondo Closs si tratta di un passaggio necessario laddove le aziende hanno l'esigenza di produrre sempre più tipi di documentazione tecnica e di prodotto, per più canali, destinatari, lingue e mercati, e in tempi sempre più rapidi. L'analisi di Closs considera in particolare l'esigenza di produrre documentazione per il mobile, che deve dare all'utente la possibilità di accedere immediatamente a contenuti rilevanti e contestuali (per esempio al luogo e al tipo di attività che sta svolgendo, al prodotto che sta utilizzando, al suo livello di conoscenza, ecc.). La documentazione monolitica, concepita per una fruizione sequenziale e difficilmente trasformabile in altri tipi di pubblicazione, non è adatta a rispondere a queste sollecitazioni complesse. Ecco il perché di una guida a come migrare verso una gestione orientata sui principi del single sourcing e del single source publishing.

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
Documentazione tecnica e di prodotto: perché e come passare
dalla “documentazione monolitica” al single sourcing e al
single source publishing
Report sul libro di Sissi Closs, Single Source Publishing, Entwickler.Press, Frankfurt a.M.,
2011
Perché passare dal dalla “documentazione monolitica” al
single sourcing e al single source publishing
Il libro di Sissi Closs è dedicato al passaggio dalla "documentazione monolitica" (p. 28 – espressione utilizzata
anche da Alessandro Stazi nel suo blog http://artigianodibabele.blogspot.it/) al single sourcing e al single
source publishing.
Secondo Closs si tratta di un passaggio necessario laddove le aziende hanno l'esigenza di produrre sempre più
tipi di documentazione tecnica e di prodotto, per più canali, destinatari, lingue e mercati, e in tempi sempre
più rapidi.
L'analisi di Closs considera in particolare l'esigenza di produrre documentazione per il mobile, che deve dare
all'utente la possibilità di accedere immediatamente a contenuti rilevanti e contestuali (per esempio al luogo e al
tipo di attività che sta svolgendo, al prodotto che sta utilizzando, al suo livello di conoscenza, ecc.).
La documentazione monolitica, concepita per una fruizione sequenziale e difficilmente trasformabile in altri tipi
di pubblicazione, non è adatta a rispondere a queste sollecitazioni complesse.
Ecco il perché di una guida a come migrare verso una gestione orientata sui principi del single sourcing e del
single source publishing.
Che cosa si intende per single sourcing e single source
publishing?
Il single sourcing si basa su:
•
Modularizzazione e standardizzazione della struttura dei contenuti
•
Gestione non ridondante dei contenuti con l'obiettivo di stabilire un unico "single point of truth"
•
Standardizzazione dei contenuti con l'obiettivo di esprimere concetti uguali in modo uguale
•
Standardizzazione della relazione fra contenuti
•
Marcatura dei contenuti con metadati (relativi, per esempio, a provenienza, stato, contesto d'uso, ecc.)
•
Separazione tra contenuto e presentazione.
Il single source publishing, cioè il corrispondente processo di pubblicazione dei contenuti, si basa su:
•
Standardizzazione della struttura dei vari tipi di documento per i vari canali e i vari destinatari (per esempio:
manuale di installazione, manuale di uso, manuale di manutenzione, help online, catalogo ricambi, ecc.)
•
Realizzazione dei documenti basata sul riuso condizionale e sull'aggregazione condizionale dei contenuti
•
Per riuso e aggregazione condizionale si intende il filtraggio dei contenuti in base ai metadati e alla
struttura del documento di destinazione
1
Documentazione tecnica e di prodotto: perché e come passare dalla “documentazione monolitica” al single
sourcing e al single source publishing – Febbraio 2014

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
•
I metadati definiscono quali contenuti vanno pubblicati, in base - per esempio - al destinatario della
comunicazione, al suo livello, alla lingua e alla nazione in cui opera, al tipo di documento e di canale,
ecc.
•
La struttura del documento di destinazione definisce la sequenza dei contenuti, nonché la modalità di
fruizione degli stessi.
Modularizzazione e standardizzazione
Il fulcro del single sourcing / single source publishing è costituito dai concetti di modularizzazione e
standardizzazione di:
•
Struttura dei contenuti
•
Contenuti
•
Relazione fra contenuti
•
Struttura dei documenti.
Closs pone l'accento sul fatto che modularizzazione e standardizzazione sono raggiungibili solo se contenuti,
relazioni e documenti non sono considerati singolarmente, ma come appartenenti a classi.
La classe è un insieme omogeneo di elementi. Per esempio in DITA i contenuti (topic) sono classificati in Concept
(concetti), Reference (voci, per esempio come quelle di un glossario) e Taks (attività-obiettivo).
Dopo aver classificato tipi di contenuto, di relazioni e di documenti, per ogni classe è possibile definire struttura dei
dati e caratteristiche di vario tipo (per esempio: quali sono contenuti obbligatori e facoltativi, che tipi di contenuti
sono ammessi, quali sono le dipendenze e le relazioni fra i contenuti, quali sono i metadati da assegnare, qual è la
forma di presentazione, ecc.).
Modularizzare e standardizzare la struttura dei contenuti
In primo luogo Closs si sofferma sulla modularizzazione e standardizzazione della struttura dei contenuti e dei
contenuti stessi.
Riferendosi
in
modo
particolare
allo
standard
DITA
(vedi
il
nostro
post
su
DITA:
http://blognew.aruba.it/blog.keanet.it/Viaggio_alla_scoperta_dello_standard_DITA_per_la_redazione_e_pubblicazi
one_di_documentazione_tecnica_76251.shtml), l'autrice propone un modello di gestione dei contenuti basato sul
concetto di "topic".
Il topic è un segmento di contenuto autosufficiente, ma tale da poter essere aggregato ad altri topic per dare
vita a testi di senso compiuto.
Le dimensioni, cioè la granularità del segmento sono variabili: un segmento può essere costituito da un intero
capitolo, da un insieme di paragrafi, da un singolo paragrafo o da un frammento di testo destinato a essere inserito
all'interno di un paragrafo.
In linea generale il dimensionamento dei topic si orienta sui principi di assenza di ridondanza, focalizzazione su
un singolo tema e capacità di riuso.
Dimensioni e struttura dei vari tipi di topic possono essere definiti in base a convenzioni aziendali oppure a
metodologie (per esempio Information Mapping, Functional Design, ecc.) o a standard (per esempio DITA,
S1000D, ecc.).
I principali vantaggi della gestione dei contenuti topic oriented sono:
•
Aumentare la produttività riducendo il volume dei contenuti da redigere, gestire e tradurre. Closs sottolinea
che, rispetto alla gestione monolitica della documentazione, la gestione topic-oriented comporta una riduzione
media del volume del 30-40%
2
Documentazione tecnica e di prodotto: perché e come passare dalla “documentazione monolitica” al single
sourcing e al single source publishing – Febbraio 2014

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
•
Rendere possibile la collaborazione fra più autori, grazie alla standardizzazione della struttura dei contenuti e
delle norme redazionali / controlli linguistici / linguaggi controllati in base ai quali redigere i contenuti stessi.
Standardizzare significa rendere esplicito e quindi condivisibile un sapere
•
Associare metadati ai contenuti
•
Riusare i contenuti
•
Favorire la scalabilità, la coerenza e la fruibilità dei contenuti, nonché la loro articolazione a vari livelli di
approfondimento
•
Aprire le porte all'automazione editoriale, cioè all'uso di applicazioni in grado di filtrare i contenuti in base ai
metadati e aggregarli in automatico in vari tipi di documenti, rivolti a vari destinatari e pubblicabili attraverso
vari canali
•
Supportare la realizzazione di documenti che prevedono un accesso non sequenziale ai contenuti (per
esempio gli help online o l'accesso diretto, tramite QR code, a contenuti rilevanti in un determinato contesto di
utilizzo).
Modularizzare e standardizzare la relazione fra contenuti
In secondo luogo Closs si sofferma sulla standardizzazione delle relazioni fra topic e fra topic e altri tipi di
contenuti (per esempio fonti dati esterne oppure software da attivare).
Fra le regole evidenziate dall'autrice in particolare quelle di:
•
Inserire solo link essenziali per non distrarre l'utente
•
Informare l'utente sulla destinazione del link
•
Presentare il contenuto di destinazione nel suo contesto per non disorientare l'utente.
Modularizzare e standardizzare la struttura dei documenti
In terzo luogo Closs affronta il tema della standardizzazione dell'aggregazione condizionale di topic, cioè della
realizzazione della documentazione tecnica e di prodotto.
Nell'ambito della gestione topic-oriented dei contenuti, il documento non è un'entità monolitica, ma frutto
dell'aggregazione condizionale dei topic intorno alla struttura standardizzata di un determinato tipo di
documento (per esempio di un manuale, di un help online, di un catalogo ricambi, ecc.).
Le condizioni di aggregazione, applicate ai metadati associati ai topic, sono per esempio:
•
Destinatario, livello del destinatario e obiettivo della comunicazione
•
Lingua, nazione o mercato
•
Tipo di documento da realizzare
•
Canale di pubblicazione.
Flusso di lavoro del single sourcing / single source publishing,
e l’adozione di authoring tool e sistemi di content management
(CMS)
Infine Closs dedica ampio spazio a considerazioni all'impatto che il passaggio al single sourcing / single source
publishing ha sull'organizzazione, sui processi e sui flussi di lavoro.
3
Documentazione tecnica e di prodotto: perché e come passare dalla “documentazione monolitica” al single
sourcing e al single source publishing – Febbraio 2014

4. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel. / Fax: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
In molti casi il passaggio al single sourcing / single source publishing è accompagnato dall'adozione di un software
dedicato (per esempio un tool di authoring o un sistema di content management [CMS]).
Come risulta anche dalle nostre esperienze di adozione di Argo CMS (vd. http://www.keanet.it/argoManuali.htm)
da parte delle aziende, l'autrice sconsiglia nel modo più vivo di migrare 1:1 nel nuovo ambiente l'archivio storico
dei contenuti.
Questo tipo di migrazione rischia infatti di creare solo svantaggi:
•
Senza un preventivo lavoro di modularizzazione e standardizzazione di contenuti e documenti, anche il
software più sofisticato non è in grado di produrre vantaggi in termini di ottimizzazione dei tempi e costi di
redazione, revisione, traduzione e pubblicazione
•
Inizialmente, la novità dell'ambiente rallenta l'operatività degli utenti.
Prima di scegliere e adottare un tool di authoring o un sistema di content management (CMS) Closs consiglia alle
aziende di seguire un vero e proprio allenamento basato su tre blocchi:
1. Allenarsi alla modularizzazione e strutturazione di documenti e contenuti, utilizzando gli strumenti
già in uso. Gli obiettivi potrebbero essere: individuare parti comuni a livello di capitolo (es. informazioni sul
copyright, tavole di descrizione dei pittogrammi, informazioni generali sulla sicurezza) e armonizzare
contenuti ripetitivi eliminando le ridondanze
2.
Testare nuovi software simulando scenari di utilizzo basati su documenti e contenuti reali già gestiti
dall'azienda
3. Allenare alla collaborazione il team di redazione, poiché la gestione dei contenut topic-oriented è
tendenzialmente un lavoro di gruppo, un processo modulare, iterativo e incrementativo, che ricalca quello
dell'Extreme Programming (XP) nell'ambito dello sviluppo software.
Autore: Petra Dal Santo (dalsanto@keanet.it)
www.keanet.it
http://blog.keanet.it/
4
Documentazione tecnica e di prodotto: perché e come passare dalla “documentazione monolitica” al single
sourcing e al single source publishing – Febbraio 2014