Report sul libro di Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt, DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, IBM Press, 2011

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
Viaggio alla scoperta di DITA, standard
per la redazione e pubblicazione di
documentazione tecnica
Report sul libro di Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt, DITA Best
Practices: A Roadmap for Writing, Editing, and Architecting in DITA, IBM Press,
2011
Introduzione
Darwin Information Typing Architecture (DITA) è uno standard definito e gestito dall’ OASIS DITA Technical
Committee.
Si tratta di una metodologia di editing in formato XML (semantico) e di publishing multicanale (mediante il
DITA Open Toolkit) a supporto della redazione e della pubblicazione di documentazione tecnica basata sui
principi del task-oriented writing e del minimalistic writing.
Il task-oriented writing focalizza i contenuti non sulle funzioni del prodotto, ma sugli obiettivi dei vari tipi di
utente e sulle procedure che essi devono seguire per raggiungerli.
Il minimalistic writing afferma invece che è necessario fornire solo le informazioni che servono, quando
servono, in base al tipo di utente, al suo livello e al contesto in cui opera.
DITA standardizza in particolare:
• La redazione di topic (articoli, argomenti) che spiegano all’utente come raggiungere un goal (obiettivo)
reale
• La struttura di navigazione dei contenuti
• I link fra contenuti
• La marcatura dei contenuti
• Il conditional processing, cioè l’inclusione / esclusione di un contenuto all’interno di una pubblicazione
• Il riuso dei contenuti, cioè la gestione di istanze di uno stesso contenuto
• La pubblicazione automatizzata dei contenuti, in particolare in formato PDF e HTML.
Vantaggi dell’adozione di DITA
Secondo le autrici, l’adozione di DITA comporta in particolare i seguenti vantaggi:
• Per il technical writer:
• Efficienza:
1
DITA – Darwin Information Typing Architecture – Agosto 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
• Gestione collaborativa
• Risparmio di tempi e costi di redazione, modifica e traduzione, grazie al single sourcing, al riuso
dei contenuti e alla possibilità di taggare testi da non tradurre
• Facilità nell’organizzazione e riorganizzazione dei contenuti, grazie alla frammentazione dei
contenuti in unità discrete e al single sourcing
• Coerenza e accuratezza, grazie alla propagazione automatica delle modifiche
• Risk management, con riduzione del rischio di disallineamento, anche in presenza di modifiche last
minute
• Per l'utente:
• Sommari, alberi di navigazione gerarchica, link a contenuti correlati, indici, organizzazione dei
contenuti incentrata su goal, task e step permettono all’utente di trovare e utilizzare con maggiore
facilità le informazioni di cui necessita
• Per l’azienda:
• DITA supporta un approccio self-helf alla fornitura dei contenuti della documentazione, che
permette di risparmiare costi di assistenza tecnica e di influire positivamente sull’immagine
aziendale.
Software
Gli strumenti software a cui le autrici fanno riferimento sono:
• XMetal (http://xmetal.com/) come tool di authoring di contenuti secondo lo standard DITA
• DITA Open Toolkit (http://sourceforge.net/projects/dita-ot/) come tool open source per il publishing
multicanale di contenuti DITA (per esempio in formato PDF e HTML).
Panoramica su DITA
Tipi di DITA topic: task topic, concept topic, reference topic
Per standardizzare la redazione di contenuti incentrati sugli obiettivi dei vari tipi di utente e sulle procedure
che essi devono seguire per raggiungerli, DITA parte dal concetto di topic (articolo, argomento).
I topic possono essere di tre tipi:
1. Task topics: descrivono task (compiti) e step (passaggi), ovvero la procedura che l'utente deve seguire
per raggiungere un goal
2. Concept topic: definiscono concetti a supporto della descrizione di task. Il grado di approfondimento
dipende dal livello e dal background dell’utente
3. Reference topic: sono dedicati a contenuti di tipo enciclopedico (per esempio liste di componenti, di
comandi, ecc.). L'ordine di esposizione può essere logico, alfabetico, cronologico, spaziale, purché
intelligibile da parte dell'utente.
2
DITA – Darwin Information Typing Architecture – Agosto 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
Dal momento che DITA è focalizzato sui concetti di single sourcing (gestione univoca dei contenuti) e riuso
dei contenuti, ogni topic deve essere dedicato a un solo argomento e redatto in modo tale sia da poter
esistere come contenuto stand-alone, sia da risultare componibile con altri topic per creare un flusso logico
di informazioni relative ai task, nonché a concept e reference di supporto.
Ogni topic deve quindi essere di senso compiuto, non contenere linguaggio relazionale (cioè termini come
prima / dopo, sopra / sotto, ecc.), né riferimenti stabili a prodotti, ecc., specifici.
Struttura di navigazione dei contenuti e link fra contenuti
Le DITA map (mappe e sotto-mappe in formato XML) strutturano i topic per guidare la realizzazione delle
pubblicazioni, nonché la sequenza di fruizione / il flusso di navigazione dell’utente.
Come i topic, anche le mappe devono raggruppare un solo insieme omogeneo (set) di informazioni,
comprendendo la sequenza dei task necessari a raggiungere un goal, supportati all'occorrenza da concept e
reference.
Per creare modelli di contenuti, a partire dai quali realizzare le mappe, le autrici consigliano l’utilizzo di
software specifici come Information Architecture Workbench di IBM, gratuito
(http://www14.software.ibm.com/webapp/download/preconfig.jsp?id=2009-09-
02+13:57:13.308214R&S_TACT=&S_CMP=).
La fruizione dei contenuti non è guidata solo dalle mappe, ma anche dai link fra contenuti. DITA supporta
vari tipi di link:
• Link gerarchici: sono creati a partire dalle mappe e presentati sotto forma di sommari o albero di
navigazione gerarchica
• Link inline: si tratta di link posti nel flusso di testo, il cui uso non è tuttavia consigliato, perché rendono
più difficoltosa la lettura, interrompendone il ritmo, e creano dipendenze fra i topic limitandone il riuso
• Relationship tables: stabiliscono relazioni fra un topic e altri topic dedicati a task, concept e reference
correlati. DITA permette di gestire link univoci o biunivoci fra topic
• Collection type link: esplicitano il legame tra elemento padre e figli, nonché tra figli di pari grado. DITA
permette di gestire i link come sequenza (lista ordinata, con link al topic successivo / precedente),
opzione o lista non ordinata, nonché famiglia (lista non ordinata con link circolari figli pari grado di uno
stesso elemento padre).
Marcatura dei contenuti, conditional processing, riuso dei contenuti
In DITA la marcatura dei contenuti è finalizzata, in particolare, al conditional processing (cioè alla
realizzazione di pubblicazioni mirate per singoli tipi di destinatari e formati di output), al reperimento dei
contenuti (tramite motori di ricerca, funzioni di faceted browsing, ecc.), nonché alla creazione di indici
(analitici, per codice componente, per comandi, ecc.).
DITA permette di gestire vari tipi di marcatori:
• Voce di un indice
3
DITA – Darwin Information Typing Architecture – Agosto 2013

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
• Attributo / valore per il conditional processing
• I conditional processing attribute possono essere standard (audience, platform, product, review) o
personalizzati (nel qual caso è consigliabile la creazione di attributi con valenza semantica)
• A ogni topic, mappe e relationship table è possibile applicare uno o più attributi, nonché uno o più
valori per attributo
• Attributi e valori sono ereditati secondo una logica top-down: attributi e valori associati alla mappa
sono ereditati da tutti gli elementi inclusi nella mappa; attributi e valori associati a un elemento
padre sono ereditati dagli elementi figli; attributi e valori associati al singolo topic non v ereditati
• Attributo di importanza (per esempio: opzionale, obbligatorio, ecc,)
• Stato (per esempio: contenuto nuovo, aggiornato, da tradurre, ecc.)
• Metadati per relativi ai credits (autore, revisione, note legali, ecc.).
Applicando un conditional processing schema ai conditional processing attribute utilizzati per marcare
topic, mappe e relationship table, è possibile includere / escludere automaticamente un contenuto in / da
un output mirato a un determinato tipo di destinatario. Il conditional processing schema specifica attributo,
valore e azione in base a cui riprendere i contenuti. Le azioni gestite da DITA sono: includi, escludi e flag,
che comporta l’evidenziazione automatica del contenuto all’interno dell’output.
Mentre il conditional processing automatizza la pubblicazione mirata dei contenuti, le specifiche di DITA
dedicate al riuso hanno l’obiettivo di regolamentare la creazione di istanze di un contenuto. Il riuso si basa
sui concetti di single sourcing (gestione univoca del contenuto) e information transclusion (inclusione
mediante link di un documento o di parte di esso in un altro documento. Vd. Wikipedia:
http://en.wikipedia.org/wiki/Transclusion). DITA permette di riusare:
• Elementi, cioè parti del contenuto di un topic (mediante l’attributo conref [content reference])
• Topic (mediante l’attributo copy-to)
• Mappe.
Per agevolare la manutenzione dei contenuti e rendere certa la propagazione delle modifiche, è
consigliabile definire con precisione i contenuti destinati al riuso.
Consigli per la migrazione verso DITA
Il libro è molto ricco di consigli pratici per migrare verso DITA e scrivere contenuti efficaci. Eccone alcuni di
particolare rilievo:
• Le autrici consigliano di esternalizzare la migrazione, affidandosi a esperti, a meno che la maggior parte
dei contenuti non sia da riscrivere. L’esternalizzazione garantisce la qualità della migrazione e permette
a team di redazione aziendale di continuare a essere produttivo
• Alla domanda se sia preferibile intervenire sui contenuti prima o dopo la migrazione, le autrici non
rispondono in modo univoco. Intervenire sui contenuti prima della migrazione ha il vantaggio di
eliminare contenuti superflui e di migrare contenuti già verificati. L’intervento a posteriori permette
4
DITA – Darwin Information Typing Architecture – Agosto 2013

5. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)
Tel. / Fax: +39 045 6152381
Web: www.keanet.it | E-mail: info@keanet.it
invece di sfruttare le funzionalità del software prescelto (per esempio di XMetal) a supporto della
riscrittura e riorganizzazione di contenuti
• In ogni caso è necessario standardizzare i contenuti, individuando duplicati e quasi duplicati,
riscrivendoli per renderli univoci
• Le autrici dedicano una particolare attenzione all’elemento shortdesc (short description). Le descrizioni
brevi dei topic sono fondamentali, perché rappresentano il primo paragrafo del topic, appaiono come
anteprima dei link e sono visualizzate nei risultati dei motori di ricerca (Google, ecc.). Le descrizioni
brevi sono fondamentali per orientare l’utente e devono essere: concise (non superiori a 35 parole),
accurate (descrivere il topic sottolineando goal, benefit, ecc.) e redatte intorno a parole chiave che
fanno parte del background dei vari tipi di utente
• Interessanti le notazioni su tabelle (in cui non inserire testi lunghi e che non dovrebbero superare le 5
colonne) e convenzioni nella nominazione dei file (a cui assegnare nomi parlanti, con o senza
riferimenti a nomi di prodotti, in base al fatto che il contenuto del file è specifico o generico).
Interessante notare che, nell’esperienza delle autrici, la conversione dei contenuti in DITA (cioè
l’inserimento dei contenuti nel software prescelto) assorba in media solo il 5% del tempo complessivo di
migrazione, grazie alle funzioni di importazione automatica di cui i tool sono normalmente dotati. La
maggior parte del tempo va dedicata alla preparazione dei contenuti e alla loro ottimizzazione una volta
convertiti.
Autore: Petra Dal Santo
www.keanet.it
http://blog.keanet.it/
5
DITA – Darwin Information Typing Architecture – Agosto 2013