Share |

Viaggio alla scoperta dello standard DITA 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:
      • 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:

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:

  • Task topics: descrivono task (compiti) e step (passaggi), ovvero la procedura che l'utente deve seguire per raggiungere un goal
  • Concept topic: definiscono concetti a supporto della descrizione di task. Il grado di approfondimento dipende dal livello e dal background dell’utente
  • 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.

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.

Panoramica su DITA

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).

Panoramica su DITA

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
  • 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 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

Demo online di Argo CMS

Contattaci per una demo online del sistema di Content Management Argo CMS per la gestione dei contenuti della documentazione tecnica.