Aufgabe

(Auszug aus "DITA - Der neue Standard für Technische Dokumentation" von Johannes Hentrich)

Die Anleitungen für einen Nutzer etwas zu tun, so genannte Handlungsanweisungen, gehören in der Technischen Dokumentation zu den wichtigsten Informationsstrukturen. Mit Handlungsanweisungen erhält der Nutzer Antworten auf die Frage: „Wie tue ich ...?“.

Handlungsanweisungen bieten die ideale Informationsgrundlage für ein Topic. Eine abgeschlossene Handlungsanweisung liefert genau ein Ergebnis, nämlich wie eine Aufgabe erfolgreich bewältigt werden kann. Damit sind die Voraussetzungen für ein in sich abgeschlossenes Topic bestens erfüllt.

DITA stellt für Handlungsanweisungen den Topictyp „Aufgabe“ (task) zur Verfügung. Das Kernstück des Topictyps „Aufgabe“ stellt eine Liste mit den einzelnen Handlungsschritten (steps) dar, das heißt, eine Schritt-für-Schritt-Anweisung. Das <step>-Element, welches einen einzelnen Handlungsschritt auszeichnet, ist eine Spezialisierung des <li>-Elements, das heißt des Listen-Elements.

Die Grundstruktur für ein Topic vom Typ „Aufgabe“ sieht wie folgt aus:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//ELEMENTS DITATask//EN" "../dtd/task.dtd">
<task id="kapitel8_task">
    <title>Computer ausschalten</title>
    <taskbody>
        <steps>
            <step>
                <cmd>Klicken Sie auf START, um...</cmd>
            </step>
        </steps>
    </taskbody>
</task>

Wie jedes DITA-Topic beginnt das Topic vom Typ „Aufgabe“ auch mit einer XML- und der DOCTYPE-Deklaration. In der DOCTYPE-Deklaration wird die task.dtd-Datei referenziert, die wiederum auf die task.mod-Datei verweist, in der die Elemente für den Topictyp „Aufgabe“ referenziert sind.

Der Topictyp „Aufgabe“ wird mit dem Wurzel-Element <task> identifiziert. Dem <task>-Element muss eine eindeutige Kennung, das heißt eine ID, zugewiesen werden.

Im <title>-Element können Sie einen Titel für das Topic vergeben. Der Titel sollte den Inhalt des Topics möglichst genau wiedergeben.

Das <taskbody>-Element legt die Struktur des Topictyps „Aufgabe“ fest. In dem obigen Beispiel ist in dem <taskbody>-Element nur ein einziger Handlungsschritt enthalten.

Ein Topic vom Typ „Aufgabe“ kann beliebig viele Handlungsschritte (<step>-Elemente) enthalten, jedoch nur einen einzigen Handlungsblock, gekennzeichnet durch das <steps>-Element. Die <step>-Elemente werden vom DITA Open Toolkit durchnummeriert. Sollen die einzelnen Handlungsschritte nicht nummeriert werden, so verwenden Sie statt des <steps>-Elements das <steps-unordered>-Element.

Die eigentliche Anweisung, die gemäß der DITA-Sprachspezifikation in direkter Rede verfasst sein sollte, wird mit dem <cmd>-Element (command) ausgezeichnet. Dies ist im Übrigen einer der wenigen Hinweise bei DITA, wie der Inhalt in einem Element formuliert werden soll.

Die in der Grundstruktur des Topictyps „Aufgabe“ bereitgestellten Informationen sind für den Nutzer kaum ausreichend, um eine Handlung erfolgreich durchführen zu können. Daher bietet DITA zahlreiche weitere Elemente an, um zusätzliche und weiterführende Informationen zu einer Handlungsanweisung bieten zu können:

  • <prereq>: In dieses Element werden alle Informationen gepackt, die der Nutzer haben muss, bevor er eine Aufgabe ausführen kann.
<taskbody>
    <prereq>Um das FO-Plugin installieren zu können, benötigen Sie folgende Software...</prereq>
    <steps>
       ...
    </steps>
</taskbody>
  • <context>: Dieses Element enthält kurze Hintergrundinformationen zum Handlungsblock. Solche Informationen können beispielsweise notwendig sein, wenn dem Nutzer mitgeteilt werden soll, was der Zweck der Handlungsanweisung ist.
<taskbody>
    <context>Wenn Sie das kleine Paket des DITA Open Toolkits installieren, benötigen Sie...</context>
</taskbody>
  • <choices>: Wenn während eines Handlungsschritts dem Nutzer eine Auswahl an möglichen Aktionen zur Verfügung steht, können Sie das <choices>-Element verwenden. Die einzelnen Möglichkeiten werden in je einem <choice>-Element angegeben.
<step>
    <cmd>Wählen Sie eine Datenbank aus.</cmd>
    <choices>
        <choice>Wählen Sie „localhost“, wenn sich die Datenbank auf dem lokalen Server befindet.</choice>
        <choice>Wählen Sie 77.12.25.124, wenn sich die Datenbank nicht auf dem lokalen Server befindet.</choice>
    </choices>
</step>
  • <choicetable>: Steht dem Nutzer während eines Handlungsschrittes eine ganze Reihe von Möglichkeiten zur Verfügung, so können Sie diese Möglichkeiten in einer Tabelle auflisten. Den Tabellenkopf definieren Sie mit dem <chhead>-Element, dem <choptionhd>-Element und dem <chdeschd>-Element. Für die Definition der Zellenelemente stehen das <chrow>-Element, das <choption>-Element und das <chdesc>-Element zur Verfügung. Das <choicetable>-Element wird innerhalb eines <step>-Elements verwendet.
<choicetable>
    <chhead>
        <choptionhd>Geben Sie %1 ein.</choptionhd>
        <chdeschd>Diese Defaulteinstellung speichert die Datei auf dem zentralen Server.</chdeschd>
    </chhead>
    <chrow>
        <choption>Geben Sie %2 ein.</choption>
        <chdesc>Die Datei wird auf dem Backup-Server gespeichert.</chdesc>
    </chrow>
    <chrow>
        <choption>Geben Sie %3 ein.</choption>
        <chdesc>Die Datei wird lokal gespeichert.</chdesc>
    </chrow>
</choicetable>
  • <info>: Mit dem <info>-Element können Sie weitere Informationen zu den einzelnen Handlungsschritten bereitstellen. Das <info>-Element wird innerhalb eines <step>-Elements verwendet.
<taskbody>
    <steps>
        <step>
            <cmd>Geben Sie den Dateinamen ein.</cmd>
            <info>Der Dateiname darf keine Sonderzeichen enthalten.</info>
        </step>
    </steps>
</taskbody>
  • <substeps>: Muss ein einzelner Handlungsschritt, definiert durch ein <step>-Element, in weitere Teilschritte aufgegliedert werden, so steht dafür das <substeps>-Element zur Verfügung. Ähnlich wie das <steps>-Element kann das <substeps>-Element mehrere <substep>-Elemente enthalten. Auch hier werden die eigentlichen Anweisungen mit dem <cmd>-Element erfasst.
<steps>
    <step>
        <cmd>Geben Sie die Umgebungsvariable CLASSPATH ein.</cmd>
        <substeps>
            <substep>
                <cmd>Um eine Umgebungsvariable zu definieren, wählen Sie....</cmd>
            </substep>
        </substeps>
    </step>
</steps>
  • <stepresult>: In diesem Element können Sie das Resultat eines einzelnen Handlungsschritts angeben.
<taskbody>
    <steps>
        <step>
            <cmd>Speichern Sie den Datensatz ab.</cmd>
            <stepresult>Die Meldung „Datenbank wurde aktualisiert.“ wird angezeigt.</stepresult>
        </step>
    </steps>
</taskbody>
  • <stepxmp>: Wollen Sie zu einem einzelnen Handlungsschritt ein Beispiel geben, so verwenden Sie dazu das <stepxmp>-Element. Das <stepxmp>-Element wird innerhalb eines <step>-Elements verwendet.
<taskbody>
    <steps>
        <step>
            <cmd>Geben Sie den Dateinamen ein.</cmd>
            <stepxmp>Ein gültiger Dateiname ist beispielweise einfuehrung.dita.</stepxmp>
        </step>
    </steps>
</taskbody>
  • <result>: Im <result>-Element können Sie das zu erwartende Resultat einer Handlungsanweisung angeben.
<taskbody>
    <result>Nachdem Sie alle Daten erfolgreich eingegeben haben, wird die Meldung „Datenbank wurde erfolgreich aktualisiert.“ angezeigt.</result>
</taskbody>
  • <tutorialinfo>: Wird das Topic für ein Tutorial verwendet, so können Sie zu einem Handlungsschritt weitere Informationen mit dem <tutorialinfo>-Element zur Verfügung stellen.
<taskbody>
    <steps>
        <step>
            <cmd>Geben Sie Ihr Passwort ein.</cmd>
            <tutorialinfo>Das Passwort erhalten Sie von ihrem Seminarleiter.</tutorialinfo>
        </step>
    </steps>
</taskbody>
  • <postreq>: Wenn nach dem erfolgreichen Abschluss der Handlungsanweisung von Seiten des Nutzers weitere Schritte oder weitere Aufgaben erforderlich sind, können Sie diese Informationen im <postreq>-Element erfassen.
<taskbody>
    <steps>
        <step>
            .....
        </step>
    </steps>
    <postreq>Als nächstes muss ANT installiert werden.</postreq>
</taskbody>

  

<< zurück vor >>

 

 

 

Tipp der data2type-Redaktion:
Zum Thema DITA bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2008 XLcontent Verlag
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "DITA - Der neue Standard für Technische Dokumentation" denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.

XLcontent Verlag, Pflegerstraße 40, 81247 München