DITA e L'Information Mapping

Di primo acchito, un approccio metodico, combinato alle possibilità tecniche offerte dall'XML, appare logico e molto promettente. DITA mette infatti a disposizione uno standard aperto di documentazione strutturata in formato XML. L'Information Mapping è un metodo per rappresentare e strutturare a misura di lettore le informazioni, il quale, come DITA, supporta il trattamento orientato ai topic. Il seguente articolo approfondisce principalmente l'interazione tra DITA e l'Information Mapping. Gli elementi di base valgono tuttavia anche per altri approcci metodici, ad esempio per il Funktionsdesign.

Lo standard DITA – Darwin Information Typing Architecture – ha come scopo la strutturazione orientata al topic dell'informazione. La DTD DITA (Document Type Definition) offre una serie di elementi strutturali particolarmente adatti per la documentazione tecnica. Il Single Source Publishing è supportato da strumenti che in parte sono liberamente disponibili e possono essere adattati alle esigenze individuali (DITA Open Toolkit). Ormai gli editor come XMetal o Adobe FrameMaker supportano DITA nella versione base. La "Organization for the Advancement of Structured Information Standards" OASIS, un'organizzazione internazione no-profit, gestisce DITA come standard aperto. Si tratta quindi di una serie di argomenti a favore che sicuramente hanno contribuito al "boom DITA" nella documentazione tecnica.

La struttura XML da sola non è sufficiente
Da sola, la struttura predefinita da un'unica DTD non è ancora in grado di garantire che una documentazione tecnica sia anche buona. È sì possibile controllare gli aspetti formali ed evitare gli errori strutturali già durante la creazione dell'informazione con l'editor, ma ciò non garantisce ancora la qualità dei contenuti. La pratica continua a mostrarci che per gli autori non è facile scegliere l'elemento strutturale "giusto" per un determinato tipo di informazione e preparare le informazioni in modo chiaro e comprensibile. Questa problematica si accentua all'interno dei team di redazione. Per ottenere l'uniformità della documentazione si deve sviluppare un pensiero comune sui contenuti e sulla loro preparazione. In questo caso è di aiuto limitarsi a determinati elementi e applicarli in modo uniforme. A tale scopo è però necessario definire delle regole nelle guide alla redazione e formare adeguatamente gli autori.

I problemi dal punto di vista degli autori
L'obiettivo di produrre una documentazione a misura di lettore, strutturata in modo chiaro e uniforme suscita negli autori una serie di interrogativi: In che modo dividere in moduli la documentazione? Come definire i limiti dei topic? Quali sono gli elementi necessari e da utilizzare per un topic? Come combinare i singoli moduli in una guida in linea o un manuale stampato? Come utilizzare in modo adeguato gli attributi per la produzione: on-line, stampa, macchina A, versione software B? Quali elementi usare per i vari tipi di informazione?

Questi problemi non si verificano solo durante la creazione ex-novo o la concezione della documentazione tecnica. Se si tratta di migrare in DITA dei documenti esistenti, la situazione si presenta complessa, soprattutto se i documenti non sono ancora disponibili in formato XML. I documenti a struttura lineare, con la classica struttura a capitoli, non sono ottimali per l'approccio orientato al topic di DITA. Di conseguenza, molto spesso si deve ricorrere a un esteso intervento manuale successivo.

L'IMAP come corpus di regole
L'Information Mapping, abbreviato in "IMAP", offre all'autore un metodo con basi scientifiche per produrre informazioni a misura di lettore. Questo metodo non presuppone assolutamente la presenza di un ambiente XML. L'IMAP può essere applicato servendosi di carta e penna e, naturalmente, usando un editor di testo. I punti di forza di questo metodo sono tuttavia meglio utilizzabili se combinati con un'architettura XML adeguata. L'IMAP fornisce all'autore un corpus di regole che lo aiutano nella produzione di una documentazione strutturata.

Un altro vantaggio di questo metodo è dato dal fatto che ha bisogno di pochi elementi strutturali e che la loro applicazione dà luogo automaticamente a informazioni modulari. A prima vista, i documenti creati con il metodo IMAP sembrano perfettamente armonizzati con DITA. Il metodo IMAP è addirittura indicato come "related Technology" nei Technology Reports delle "Coverpages" di OASIS. Ma DITA e IMAP vanno davvero così d'accordo?

I principali elementi di DITA
Approfondire la DTD DITA andrebbe al di là degli intenti del presene articolo, ci limiteremo quindi a una breve panoramica. La DTD DITA offre prevalentemente elementi pensati per la creazione di documentazione tecnica. L'elemento "task" è ad esempio adatto alla creazione di istruzioni d'uso suddivise in passi. Gli elementi principali contengono altri elementi per poter riprodurre tutti i contenuti della documentazione tecnica. La figura 1 mostra uno schema che rappresenta gli elementi principali della DTD DITA.

Fig. 1: i topic di DITA sono perfetti per i contenuti di una documentazione tecnica.

La struttura orientata ai topic forza la strutturazione modulare dell'informazione, il che favorisce il riutilizzo dei contenuti. È quindi possibile creare moduli di informazione che vengono poi combinati per formare la documentazione. In caso di documentazioni molto estese è tuttavia estremamente opportuno usare un Content Management System per gestire i singoli moduli.

I moduli IMAP
L'Information Mapping è basato su quattro moduli principali:

• sette principi
• due unità di informazione: mappa e blocco
• sette tipi di informazione con consigli relativi alla rappresentazione
• analisi a misura di lettore

I paragrafi che seguono mostrano possibili combinazioni tra IMAP e DITA basate su questi moduli. Gli esempi riportati sono delle proposte e non rappresentano tutte le possibilità di combinazione "giusta". Alcune regole dell'IMAP si applicano in modo diverso in DITA. Di conseguenza, per un'azienda o un team di autori è sempre necessario definire una procedura unitaria a partire da questa base.

Sette principi
L'Information Mapping definisce sette principi che devono essere rispettati dall'autore per creare una buona documentazione. DITA non consente di verificare direttamente o di garantire il rispetto di queste regole, ma la struttura della DTD DITA supporta molte esigenze dei sette principi IMAP, anche se ci sono dei limiti. Ad esempio, la DTD DITA non è in grado di riconoscere se un'informazione è rilevante per il lettore. Il rispetto del cosiddetto principio di rilevanza spetta sempre all'autore. DITA consente tuttavia ad esempio di specificare moduli di informazione per un determinato gruppo target e successivamente di considerare solo l'informazione rilevante per il gruppo target al momento della rappresentazione o della produzione.

La figura 2 mostra i sette principi IMAP e come DITA può aiutare a rispettarli.

Fig. 2: a ogni elemento IMAP corrisponde un elemento XML. Per ingrandire l'immagine, fare clic sulla grafica.

L'unità di informazione mappa e blocco
Un importante principio del metodo IMAP è la creazione di informazione modulare. A tale scopo, i contenuti vengono suddivisi in mappe, le quali a loro volta sono costituite da blocchi. La mappa IMAP può essere ottimamente riprodotta con l'elemento DITA "topic", ma non ha nulla a che vedere con l'omonima mappa DITA. La mappa DITA consente prevalentemente di raffigurare strutture logiche di contenuti.

I blocchi all'interno della mappa IMAP vengono inseriti sotto forma di task o di concept. Nell'elaborazione di un blocco si tiene conto anche del tipo di informazione, come mostrato dalla figura 3, all'interno del task o del concept vengono selezionati gli elementi consigliati dall'IMAP per rappresentare l'informazione in modo ottimale. DITA è in grado di offrire tutti questi elementi.

Fig. 3: gli elementi della struttura IMAP e la possibilità di applicazione in DITA

La mappa panoramica in IMAP serve per navigare nel corrispondente livello gerarchico e rimanda ai topic relativi. La mappa panoramica tuttavia non è costituita solo da link, ma contiene anch'essa dei contenuti, che ad esempio introducono nell'argomento oppure forniscono una breve indicazione del contenuto. Può essere applicata con l'elemento DITA "reference".

La mappa DITA è invece costituita da rimandi ai relativi topic e costituisce per così dire il sommario della documentazione. Essa lega tutti i topic della documentazione in base all'ordine e alla struttura desiderati e funge da master per la produzione della documentazione con l'Open Toolkit. Gli utilizzatori di Adobe FrameMaker conoscono un elemento simile grazie alla "funzione libro".

Fig. 4: per mantenere la visione d'insieme, l'IMAP utilizza delle mappe panoramiche. La mappa di DITA referenzia i topic, importanti per la navigazione e la produzione.

Sette tipi di informazione
Per rappresentare l'informazione nel modo migliore per il lettore, l'Information Mapping distingue tra sette tipi di informazione. Per ognuno di essi, questo metodo consiglia determinate forme di rappresentazione. Ad esempio, per le istruzioni si consiglia la cosiddetta tabella dei passi. DITA offre la relativa applicazione con l'elemento "task" e "step".

IMAP consiglia inoltre di scrivere le istruzioni in forma attiva e di rivolgersi direttamente al lettore, il che non può essere verificato direttamente con DITA. Esistono tuttavia già degli strumenti, ad esempio CLAT, che sono in grado di controllare molto di più dell'ortografia. Con delle regole di stile, ad esempio, sarebbe possibile verificare all'interno dell'elemento XML "step" se i singoli passi sono stati formulati nello stile attivo.

La figura 5 mostra i tipi di informazione di IMAP e la possibile applicazione con gli elementi DITA.

Fig. 5: ogni tipo di informazione di IMAP trova una sua corrispondenza in DITA.

La figura 6 mostra un esempio pratico di mappa di istruzioni applicata con DITA.

Fig. 6: i tag DITA sono qui rappresentati dall'editor XMetal. Vi sono inserite le informazioni configurate in base all'IMAP. Alla fine l'output può essere un PDF. Per ingrandire l'immagine, fare clic sulla grafica.

Analisi a misura di lettore
Un compito importante degli autori è determinare i contenuti che sono rilevanti per una documentazione. L'informazione contenuta non deve essere troppa, ma d'altro canto il lettore non deve avere l'impressione che manchino delle informazioni. L'IMAP aiuta gli autori a determinare il fabbisogno di informazione del lettore con una tecnica di analisi sistematica. Le possibili domande del lettore su un argomento devono trovare risposta. Occorre mettere il lettore in grado di fare e capire determinate cose tenendo conto non soltanto dello scopo della documentazione, ma anche del background del gruppo target (ad esempio principianti – esperti). L'analisi a misura di lettore si effettua prima di creare la documentazione. In questo campo DITA non offre agli autori un aiuto diretto.

Tuttavia, è possibile tenere conto dei gruppi target quando si crea la documentazione con DITA. Ad esempio, l'attributo "audience" consente di assegnare i moduli di informazione (blocco, mappa) a determinati gruppi target (ad esempio utilizzatori – tecnici dell'assistenza). Questo attributo può poi essere considerato in fase di produzione o di rappresentazione on-line della documentazione.

Riassunto
Il metodo IMAP e lo standard DITA sono complementari. Dal punto di vista tecnico, DITA aiuta l'autore nel suo lavoro e consente di creare documentazioni strutturate in modo modulare. I moduli sono riutilizzabili e rappresentabili in funzione del gruppo target, delle versioni e del supporto di output. L'IMAP apporta la metodica redazionale come strumento utile agli autori per realizzare una documentazione di buona qualità, chiara e adeguata al gruppo target. Un grande vantaggio è dato dal fatto che questo metodo può essere usato senza lavorare già in un ambiente di redazione basato su XML. I documenti IMAP possono essere migrati in DITA in modo relativamente semplice. Naturalmente sono necessari interventi quando si tratta di formati proprietari, come ad esempio Word, ma l'operazione può essere automatizzata e quindi molto più rapida rispetto ai documenti con la classica struttura lineare.

Siegfried Siegel lavora come Responsabile Tecnico presso la ditta CARSTENS + PARTNER di Monaco di Baviera. I suoi campi di attività comprendono, tra gli altri, la consulenza nell'ambito dell'introduzione di ambienti di redazione basati su XML. Inoltre, in qualità di trainer certificato del metodo Information Mapping, si occupa di metodi di strutturazione e di standard come DITA.

Siegfried Siegel - CARSTENS + PARTNER sigi.siegel@carstens-techdok.de