Darwin Information Typing Architecture (DITA) ha dato prova di essere un'eccellente soluzione per l'ottimizzazione del riuso dei contenuti. Tuttavia, chi utilizza versioni precedenti di DITA potrebbe interrogarsi sul perché utilizzare DITA 1.2 (l'ultima versione al 2011); chi non utilizza DITA potrebbe essere incuriosito dal fatto che le caratteristiche dell'ultimo DITA 1.2 potrebbero essere un buon motivo per provare DITA.

DITA – breve introduzione

Storicamente, i comunicatori tecnici hanno creato lunghi documenti in forma di libro. Ad esempio, un pacchetto software conteneva normalmente vari libri, come la guida dell'utente e il manuale di riferimento. Una quantità considerevole delle informazioni contenute in tali documenti era sovrapponibile. Tale duplicità di informazioni comportava costi maggiori poiché dovevano essere scritte, modificate, tradotte e curate diverse volte.

In contrasto rispetto ai lunghi libri, DITA scompone il contenuto in piccoli gruppi, chiamati argomenti. Un documento è composto da una mappa che indica una combinazione di argomenti che è possibile riutilizzare da più documenti. Ad esempio, le mappe per una guida dell'utente  e un manuale di riferimento potrebbero indicare molti degli stessi argomenti, oltre ad argomenti peculiari di ogni documento. Riutilizzare un argomento per diversi documenti consente di risparmiare denaro dato che andrebbe creato una sola volta, il che alletta qualsiasi manager intento a ridurre i costi.

DITA contiene i seguenti tipi di argomento:

• Attività: argomenti che descrivono come fare qualcosa guidando passo dopo passo
• Concetto: argomenti che descrivono definizioni, regole e linee guida.
• Riferimento: argomenti che descrivono la sintassi dei comandi e altro materiale di riferimento dettagliato ed effettivo
• Voce di glossario

Generalmente, ogni argomento tratta una materia specifica con una finalità. I suddetti argomenti possono essere resi più specifici creandone di nuovi che si adattano a specifiche aziende o industrie.

La mappa DITA e i documenti di argomento sono in formato XML. Esiste una molteplicità di strumenti per la modifica XML. Una volta creati i documenti relativi a mappe e argomenti, è possibile pubblicare una serie di prodotti finali, come PDF, stampe, Guida online e HTML.

DITA è stato creato da IBM ma oggi è uno standard open source, approvato e supportato da OASIS, che pubblica un kit di strumenti gratuito per il supporto all'elaborazione open source.

Modulo per attività generali

Prima della comparsa di DITA 1.2, a DITA si obiettava il fatto che non fosse in grado di gestire la complessità di alcune attività.

DITA 1.2 amplia il modello per attività generali in modo da consentire:

• Insiemi multipli di passaggi
• Avvisi all'inizio di un passaggio
• Maggiore libertà nell'organizzazione dei blocchi
• Una sezione per informazioni generiche

L'utente che crea un nuovo DTD/Schema ha la possibilità di utilizzare il modello originale con lo stesso vincolo, un vincolo nuovo o nessun vincolo (parleremo dei vincoli più avanti).

Chiavi e attributi keyref utilizzati con l'elemento <keydef>

Le chiavi e gli attributi keyref consentono di impostare uno schema di reindirizzamento, sfruttando l'architettura della mappa esistente. L'idea è associare un target a una chiave, quindi creare dei link al target utilizzando  la chiave. Ciò consente di avere dei contenuti maggiormente riutilizzabili.

Le chiavi e gli attributi keyref si riferiscono agli elementi <keydef>. <keydef> è un elemento di agevolazione – un <topicref> specializzato che imposta il valore predefinito dell'attributo  @processing-role  su "resource-only". <keydef> lega un nome chiave a una risorsa specifica, come l'indirizzo di un sito web. Ad esempio, è possibile definire un <term> o <xref> su cui i lettori possono cliccare per ottenere maggiori informazioni.

Nell'esempio seguente, viene impostata una chiave "LCD" che rimanda a Wikipedia. Il target href e la chiave "LCD" sono definiti all'interno di un <keydef> di una mappa:

<map>

<keydef

keys="lcd"

href="http://en.wikipedia.org/wiki/LCD"

format="html"

scope="external"

/>

...

</map>

La chiave può essere utilizzata per ricavare un link dal termine "LCD". Può anche essere sostituita a href:

La vostra prossima TV dovrebbe essere un <term keyref="lcd">LCD</term>.

Per maggiori informazioni, consultare <xref keyref="lcd">Wikipedia</xref>.

Il risultato sarà il seguente:

La vostra prossima TV dovrebbe essere un LCD.

Per maggiori informazioni, consultare Wikipedia.

L'attributo keyref accede al testo dalla mappa

DITA 1.2 consente all'attributo keyref su <keyword> di prendere del testo dalla mappa. In questo esempio, <keydef> è definito nel file "lcd-brand-keys.dita":

<map title="LCD TV help">

<keydef keys="lcd-brand" href=">

<topicmeta>

<keywords>

<keyword>Oak Mountain Big Screen TV</keyword>

</keywords ></topicmeta>

</keydef>

...

</map>

Ora <keyref> può far riferimento al nome del marchio:

<task ...>

...

Speriamo che la vostra TV <keyword keyref="lcd-brand" /> sarà di vostro gradimento.

Il risultato sarà il seguente:

Speriamo che la vostra TV Oak Mountain Big Screen sarà di vostro gradimento.

Estensioni dell'attributo Conref

Conref consente di includere un argomento in un altro. Più in generale, indirizza il contenuto a cui fa riferimento nella posizione dell'elemento di rimando. DITA 1.2 ha aggiunto dei miglioramenti utili che consentono di fare riferimento solo a una parte di un argomento, di fornire informazioni aggiornate sugli argomenti, oppure di preservare conref senza prendere decisioni.

Conref include/pull range

Immaginate di voler includere tre passaggi di un'altra attività, (il cosiddetto "pulling"). Prima di DITA 1.2, erano necessari tre elementi separati contenenti conref. Ora ne basta uno solo. L'operazione si effettua specificando un intervallo con il nuovo attributo conrefend insieme a quello vecchio.

In questo esempio, il file "source-file.dita" comprende tre argomenti "source-topic" che includono elementi di elenco:

<topic id="source-topic">?...?    <ol>?    <li id="first-li">Primo</li>?    <li id="second-li">Secondo</li>?    <li id="third-li">Terzo</li>?    <li id="fourth-li">Quarto</li><li id="fifth-li">Fifth</li>?...

Di seguito è mostrato un argomento di riferimento che richiama il secondo, terzo e quarto elemento in elenco dal file di origine utilizzando conref e conrefend:

<topic id="referencing-topic">?...?    <ol>?    <li>Questo elemento in elenco viene prima degli elementi in elenco inclusi</li>?    <li?conref="source-file.dita#source-topic/second-li"?conrefend="source-file.dita#source-topic/fourth-li"?    />?    <li>Questo elemento in elenco viene dopo gli elementi in elenco inclusi</li>?...

Il risultato dell'argomento di riferimento è:

Questo elemento in elenco viene prima degli elementi in elenco inclusi?Secondo?Terzo?Quarto?Questo elemento in elenco viene dopo gli elementi in elenco inclusi

Conref push

Quando un argomento inserisce delle informazioni in un altro argomento, questo processo viene chiamato "pushing". Il pushing risulta comodo  quando desiderate modificare le informazioni (come aggiungere nuovi passaggi) in un argomento esistente senza davvero modificare il file di argomento esistente. Finora era possibile soltanto modificare un argomento per "richiamare" l'informazione al suo stesso interno, come nel precedente esempio conref.

Si specifica come l'informazione viene inserita nell'argomento esistente scegliendo uno tra tre metodi:

• Inserire l'informazione appena prima di un elemento
• Inserire l'informazione appena dopo un elemento
• Sostituire l'informazione contenuta in un elemento
• L'elemento interessato viene specificato indicando il suo ID.

Conref push replace

Consente di sostituire i contenuti di un elemento. Tanto per cambiare, il nostro esempio utilizzerà l'argomento specializzato "task" invece di un argomento generico. Come mostrato di seguito, il file "source-file.dita" contiene l'argomento "source-task", che a sua volta contiene dei passaggi di attività. Come potete vedere, il terzo passaggio va sostituito:

<task id="source-task">?...?    <steps>?    <step id="first-step"><cmd>Primo comando</cmd></li>?    <step id="second-step"><cmd>Secondo comando</cmd></li>?    <step id="third-step"><cmd>Non corretto</cmd></li>?    <step id="fourth-step"><cmd>Quarto comando</cmd></li><step id="fifth-step"><cmd>Quinto passaggio</cmd></li>?...

Ecco un argomento di riferimento che sostituisce il contenuto del terzo passaggio:

<task id="pushing-task">?...?    <steps>?    <step ?conaction="pushreplace">?conref="source-task.dita#source-task/third-step"?    >?    <cmd>Questo è il terzo comando corretto</cmd>?    </step>?    ...

Il risultato pushing-task è il seguente:

Primo comando ?Secondo comando?Questo è il terzo comando corretto ?Quarto comando?Quinto comando

Conref push after

Questo esempio inserisce il nuovo contenuto dopo un elemento invece di sostituire il contenuto. Da notare come il passaggio 3 sia mancante:

<task id="source-task">?...?    <steps>?    <step id="first-step"><cmd>Primo comando</cmd></li>?    <step id="second-step"><cmd>Secondo comando</cmd></li>?    <!-- Da notare come il passaggio 3 sia mancante -->?    <step id="fourth-step"><cmd>Quarto comando</cmd></li> ...

Innanzitutto, uno <step> deve specificare il conref e il conaction="mark" (ciò evita la creazione di una struttura non valida). Successivamente, un passaggio specifica il -conaction="pushafter" e il comando mancante:

<task id="pushing-task">?...?    <steps>?    <step conaction="mark">?conref="source-task.dita#source-task/second-step"?    />?    <step conaction="pushafter">?    <cmd>Terzo comando</cmd>?    </step>?    ...

Il risultato pushing-task è il seguente:

Primo comando ?Secondo comando?Terzo comando ?Quarto comando

Conref push before

Per spostare il contenuto prima del conref specificato, invertire il segno e i passaggi conaction (inserire conaction per primo). Inoltre, bisogna specificare conaction="pushbefore". Immaginando lo stesso input e output dell'esempio precedente, ecco come inserire il passaggio 3 prima del passaggio 4:

<task id="pushing-task">?...?    <steps>?    <step conaction="pushbefore">?    <cmd>Terzo comando</cmd>?    </step>?    <step conaction="mark">?conref="source-task.dita#source-task/fourth-step"?    />?    ...

Conkeyref

L'attributo conref delle versioni precedenti di DITA richiede un riferimento diretto. Nell'esempio precedente viene specificato un file "source-task.dita":

conref="source-task.dita#source-task/fourth-step" È un procedimento lungo e scomodo. Inoltre, se doveste rinominare source-task.dita, dovreste modificare tutti i riferimenti a source-task.dita.

Conkeyref consente di aggiungere un livello di astrazione, così che invece di specificare un riferimento diretto contenente il nome di un file, è possibile specificare una chiave: conkeyref="source-task-key/fourth-step"

Ma come avviene il riferimento della chiave all'effettivo file DITA? Per far ciò, aggiungere un/una [manca una parola?] alla mappa DITA, come in questo esempio il file nominato ComeUtilizzareLaGuidaTVLCD.ditamap:

<map>?<title>Come utilizzare la TV LCD</title>?<keydef ?keys="source-task-key" ?href="source-task.dita" ?type="topic" format="dita"?/>?...

Glossari e abbreviazioni

Gli argomenti del glossario di DITA 1.1 consentivano soltanto termini e definizioni. La buona notizia è che, a partire da DITA 1.2, gli argomenti del glossario consentono termini alternativi come acronimi, sinonimi e forme abbreviate. Consentono inoltre nuove informazioni per l'uso come proprietà, stato e possibilità. Ecco un esempio di voce di glossario che utilizza molte delle nuove opzioni:

<glossentry id="lcdtv">?<glossterm>Televisore LCD</glossterm>?<glossdef>TV il cui schermo è fatto di cristalli liquidi.</glossdef>?<glossBody>?<glossSurfaceForm>?Televisore con Schermo a Cristalli Liquidi (TV LCD)?</glossSurfaceForm>?<glossPartOfSpeech value="noun"/>?<glossUsage>Non confondere LCD con LED</glossUsage>?<glossAlt>?<glossAbbreviation>schermo piatto</glossAbbreviation>?<glossStatus value="prohibited"/>?<glossUsage>?Non specifico perché comprende LED e plasma.?</glossUsage>?</glossAlt>?</glossBody>?</glossentry>

La chiave deve essere associata a un argomento:

<keydef keys="lcdtv" href="all-about-lcdtv.dita"/>

Ora può essere utilizzato nel contenuto. Gli acronimi possono essere estesi automaticamente utilizzando <abbreviated-form>:

<p>La vostra <abbreviated-form keyref="lcdtv"/> vi piacerà non appena aprirete la confezione.</p>?<p>Parlate agli amici della vostra <abbreviated-form keyref="lcdtv"/>.</p>

La prima volta verrà utilizzata la <glossSurfaceForm>, mentre per le volte successive verrà visualizzato solo l'acronimo:

Il vostro Televisore con Schermo a Cristalli Liquidi (TV LCD) vi piacerà non appena aprirete la confezione.?Parlate agli amici della vostra TV LCD.

Istruzione e formazione

Se vi occupate dello sviluppo di manuali di istruzione, DITA 1.2 vi piacerà perché comprende diversi moduli creati dal Sottocomitato DITA per l'Istruzione, esperti di manualistica. Tali moduli comprendono diverse specializzazioni di argomenti e attività utilizzate per progettare le informazioni riferite alle attività relative all'istruzione.

In un mondo complesso come quello di oggi in cui esistono molti frammenti di informazione e molti modi diversi di accedervi, gli sviluppatori di contenuti per l'istruzione e la formazione si trovano ad affrontare molteplici sfide, tra cui:

• Come trovare il contesto per sviluppare e fornire il contenuto giusto, alla persona giusta e al momento giusto?
• Come identificare i traguardi e gli obiettivi di apprendimento?
• Chi è il pubblico e quanto è vasto? Come comporre e integrare il contenuto proveniente da diverse fonti e fornitori di contenuti?
• Come permettere ai clienti e ai partner di aggiungere, integrare, assemblare e fornire il proprio contenuto?
• DITA 1.2 affronta questi problemi fornendo:
• Riutilizzo di Oggetti Didattici Riutilizzabili (RLO)
• Tipi di argomento come blocchi costituenti per oggetti didattici
• Domini per fornire il meccanismo per l'interazione e i metadati
• Mappe per organizzare gli argomenti didattici in lezioni, moduli e corsi
• Specializzazione per tipi, domini e mappe basate sulla didattica

Specializzazioni per macchinari

Se scrivete documenti per macchinari rivolti all'industria delle macchine, sarete lieti di scoprire che DITA 1.2 sostiene i vostri sforzi. Questo tipo di documento è costruito per combinare il tipo di informazioni generali sulle attività con il Task Requirements Domain e il Machinery Taskbody Constraint. Contiene elementi per i requisiti di attività speciali e si basa sugli elementi S1000D.

Creato dal Sottocomitato OASIS DITA per i Macchinari, questo capitolato fornisce informazioni su procedure, analogamente agli altri tipi di attività. La sua struttura semantica ben definita è progettata per soddisfare le speciali esigenze delle organizzazioni che sviluppano manuali di istruzione per apparecchiature industriali, come prodotti industriali, ad esempio autocarri, macchinari per estrazione e autovetture. Il dominio dei requisiti per macchinari-attività industriali aggiunge vari nuovi elementi descrittivi nelle sezioni dei requisiti preliminari (prelreqs) e requisiti finali (closereqs). Nei moduli principali vengono integrate note di avviso e attenzione:

<note type="caution1">?<note type="caution2">?<note type="danger">

Mappatura dei gruppi utilizzando <topicset> e <topicssetref>

Il nuovo elemento <topicset> consente di definire un ramo di navigazione in una mappa DITA in modo che possa essere richiamata da un'altra mappa DITA. Il nuovo elemento <topicsetref> consente di rimandare a un ramo di navigazione definito in un'altra mappa DITA.

Lo scopo principale del nuovo e agevole elemento <topicset> è definire un gruppo di argomenti che generalmente è accorpato come unità. Si potrebbe voler utilizzare queste attività in molti luoghi, ma verranno sempre utilizzate in gruppo.

In questo esempio, la nostra guida TV LCD contiene una mappa DITA chiamata lcd_tv_help.ditamap che comprende un <topicset> che rimarrà unito, a prescindere da dove verrà utilizzato:

<map title="LCD TV Help">?    <topicref format="dita" href="LCD_TV_Help.dita">?    <topicset id="installing-lcdtv" href="Installing.dita">?    <topicref href="Unpacking_LCDTV.dita" />?    <topicref href="Cabling_LCDTV.dita" />?    …?    </topicset>?    …

Ora il set argomento può essere richiamato da una mappa DITA chiamata lcd_tv_quick_start.ditamap contenente <topicsetref>:

<map title="LCD TV Quick Start">?    <mapref href="why_you_will_love_your_LCD_TV.dita">?    <mapref href="why_your_neighbors_will_love_your_LCD_TV.dita">?    <topicsetref href="lcd_tv_help.ditamap#installing-lcdtv">?</map>

<map title=""LCD"><mapref href=""why_you_will_love_your_LCD_TV.dita""><mapref href=""why_your_neighbors_will_love_your_LCD_TV.dita""><topicsetref href=""lcd_tv_help.ditamap#installing-lcdtv""></topicsetref></mapref></mapref></map>

Soggetti e schemi

Un nuovo elemento specializzato della mappa DITA chiamato <subjectScheme> consente di definire soggetti e relazioni. Ciò è utile quando bisogna definire una tassonomia, come una raccolta di valori controllati consentiti in un attributo. I soggetti possono essere associati con argomenti di altre mappe, il che fornisce metadati che è possibile utilizzare per migliorare la ricerca.

Ogni valore controllato è definito utilizzando un riferimento all'argomento specifico, chiamato <subjectdef>. Il <subjectdef> è utilizzato per definire sia una categoria che una lista di valori controllati.

Il <subjectdef> superiore definisce la categoria e quelli secondari definiscono i valori controllati. L'esempio seguente mostra l'uso del <subjectdef> per definire a quale possibile pubblico è rivolta una TV LCD. Da notare come possono essere nidificati (l'utente finale può essere un principiante o un esperto):

<subjectScheme>?<subjectdef keys="users">?<subjectdef keys="enduser">?<subjectdef keys="novice"/>?<subjectdef keys="expert"/>?</subjectdef>?<subjectdef keys="salesperson">?<subjectdef keys="techsupport">?</subjectdef>?<enumerationdef>?<attributedef name="audience"/>?<subjectdef keyref="users"/>?</enumerationdef>?</subjectScheme>

Sono disponibili elementi avanzati che specificano il tipo di relazione in una gerarchia tra un soggetto contenitore e i relativi soggetti contenuti: elementi <hasNarrower>, <hasPart>, <hasKind>, <hasInstance> e <hasRelated>. Essi possono essere sfruttati da strumenti sofisticati per creare associazioni intelligenti tra i contenuti.

Vincoli

I vincoli autorizzano gli sviluppatori di DTD e Schema a limitare i modelli di contenuto, come rimuovere del testo e delle frasi dagli elementi <section>. Ciò consente a un'organizzazione di semplificare ciò che l'autore vede senza creare una specializzazione.

Restrizioni tipiche comprendono la limitazione del modello di contenuto, gli attributi per un elemento e gli elementi di estensione da un dominio. È inoltre diffusa la sostituzione di elementi base con estensioni di dominio.

Tuttavia, per far ciò è richiesta la conoscenza di come schema (DTD/XSD) applica il vincolo. Da notare che se si utilizza uno strumento di creazione di documenti che supporta i DTD o Schema, tale strumento è dotato di un supporto base per i vincoli.

Altre funzioni

Titoli della tabella delle relazioni

Le tabelle delle relazioni spesso fissano dei tipi per ogni colonna. Le tabelle delle relazioni vengono definite con l'elemento <reltable>. Esse possono essere utilizzate per definire le relazioni tra gli argomenti DITA o tra argomenti DITA e risorse non DITA.

In DITA 1.2 è possibile aggiungere un titolo all'intestazione inserendo un topicref. I link agli argomenti in tale colonna saranno raggruppati sotto un'intestazione determinata da quell'argomento.

<sectiondiv>

Alternativa senza titolo alle sezioni nidificate.

<bodydiv>

È simile a <sectiondiv> perché consente il raggruppamento di sezioni e altri contenuti del corpo senza consentire le sezioni.

<text>

Consente il riutilizzo senza semantica di parti di testo, ma è limitato a posizioni che non consentono elementi semantici.

<coderef>

Consente di inserire del testo integrale, come un codice sorgente.

Varie

• Adattamento immagini
• Diverse enumerazioni di attributi eliminate
• Uso esteso del commento bozza in <body> e <shortdesc>
• Nuovi elementi della mappa <mapref>, <topicset> e altro

Conclusione

DITA 1.2 è un fantastico aggiornamento di DITA 1.1 che ha molto da offrire e che vale la pena analizzare. Qui di seguito vengono forniti diversi link utili che possono aiutare a saperne di più su DITA 1.2.

Riferimenti

• Wikipedia (panoramica)
• Spec DITA 1.2 di OASIS:?http://www.oasis-open.org/standards#ditav1.2?http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.pdf
• Modifiche da DITA 1.1 a DITA 1.2 (appendice alle specifiche DITA 1.2)
• Comprensione di DITA 1.2: chiavi, estensioni conref e altro?Presentazione di Robert Anderson (IBM) e Kristen James Eberlein (Eberlein Consulting)
• Il luogo di ritrovo ufficiale della comunità e le risorse di informazioni per lo Standard OASIS DITA
• DITA è stato ideato da IBM. In fondo a questa pagina ci sono link a DITA.
• Ringraziamenti speciali a Robert Anderson.

Tom Aldous, Direttore – Sviluppo commerciale e Divulgazione di Comunicazione Tecnica presso Adobe Systems, Inc., responsabile globale per lo Sviluppo commerciale di Comunicazione Tecnica e divulgazione del prodotto di Adobe. Prima di questo incarico, Tom è stato socio dirigente di Adobe Business Partner Integrated Technologies, Inc. per oltre 20 anni.