So bleibt Ihr Hilfesystem modular

Halten Sie Ihre Onlinehilfe durch ein Linkkonzept modular.

Vor fünf Jahren entwickelte meine Abteilung ein neues Softwareprodukt. Damit es neue Kunden findet, hielt ich es marketingtechnisch für eine gute Idee, die Onlinehilfe des neuen Produkts einfach mit derjenigen des bereits bestehenden, ähnlichen Produkts zu verbinden. Zumindestens im Bereich Marketing hat sich dies gelohnt. Fast alle Kunden der alten, ähnlichen Software sind inzwischen auch Nutzer der neuen Software. Eine gute Idee bis zu dem Tag, als ich die Onlinesysteme wieder trennen wollte. Es ging nicht! Die ursprünglich zwei Hilfen waren zu einem festen Monolithen zusammengeschweißt. Ich hatte wild untereinander verlinkt, und das direkt durch xref-Verlinkung! Denn beide Softwareprodukte nutzen gemeinsam bestimmte Programmteile wie die Nutzerverwaltung oder die Gerätesteuerung für Drucker und Scanner.

Bis ich auf Priscilla Buckleys Artikel From Monolithicity to Flexibility, Using DITA Keyrefs stieß. Priscilla Buckley stand bei SAP vor einem viel größerem Problem: die Basisdokumentation bei jedem SAP-Update bestand aus 50.000 Topics. Es galt, die Onlinehilfe in Komponenten zu splitten.

Dependency Tree

Sie fingen bei SAP an, innerhalb der Software die einzelnen Komponenten zu identifizieren und sie auf 13 Content Layer zu verteilen.

sap-2
Schichten, Content Container und Verlinkungsbäume

Nachfolgend meine Erfahrungen bei der praktischen Umsetzung von Buckleys Konzept. Um diese zu verstehen, bitte ich Sie, Buckleys Artikel zu lesen.

Ich habe ein Softwareprodukt (product), welches eine Komponente hat (product-reuse), die noch von anderen Teilen des Programms genutzt wird. Das kann z.B. ein Graphik-Import-Modul sein. Dann gibt es auf Plattform-Ebene noch eine Komponente, die nichts mit der eigentlichen Fachanwendung zu tun hat, nämlich die Benutzerkonto-Einstellungen (technical-reuse). Diese werden ebenfalls von mehreren Produkten und Komponenten genutzt.

General-Example-Dependency-Tree
Drei Content-Container in bestimmten Schichten

Das Produkt 08-product (z.B. ein Textverarbeitungsprogramm) ist in der Fachanwendung auf Layer 8 angesiedelt. Von dort darf verlinkt werden zu Layer 06 (Graphik-Import) und zu Layer 2 (Benutzerkonto-Einstellungen). Jedoch darf nicht umgekehrt von Layer 6 hinauf zum Produkt, Layer 8 verlinkt werden! Denn das Graphik-Importmodul ist ja noch in anderen Produkten, die ebenfalls den Graphik-Import nutzen, eingebunden. Dort gäbe es nun broken links, denn es können keine Links auf das Produkt Textverarbeitung aufgelöst werden.

Ebenso darf vom Layer 2 Benutzerkonto-Einstellungen (02-technical-reuse) nicht hinauf auf das Graphik-Importmodul (06-product-reuse) auf Layer 6 verlinkt werden! Die Benutzerkonto-Einstellungen sind in vielen anderen Publikation enthalten, die jedoch nicht immer das Graphik-Importmodul enthalten.

Ditamap für die Publikation

Es soll eine Extra-Publikation “Das Graphik-Importmodul” für das Graphik-Importmodul veröffentlicht werden. Letztere könnte so aussehen, denn sie enthält ein Kapitel zum Graphik-Import und eins zu den Benutzerkonto-Einstellungen.

graphik-import-publikation.ditamap

Die Mapdatei für die Publikation “Das Graphik-Importmodul”.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
"http://docs.oasis-open.org/dita/v1.2/os/dtd1.2/technicalContent/dtd/map.dtd">
<map id="product" scope="local" title="Textverarbeitung" xml:lang="de-de">
  <mapref href="06-product-reuse/graphik-import_content.ditamap"/>
  <mapref href="02-platform-reuse/user_content.ditamap"/>
</map>

Content-Maps

Die oben via mapref referenzierten Ditamaps haben folgende Reihenfolgen bezüglich der Inhalte.

graphik-import_content.ditamap

Die Map für das Anordnen (die Reihenfolge) der Topics für das Graphik-Importmodul sieht so aus. Man beachte, dass die Topics per keyref referenziert werden, und nicht mit href.

<map id="graphik-import_content" title="Graphik-Import" xml:lang="de-de">
  <mapref href="06-product-reuse/graphik-import/graphik-import_container.ditamap processing-role="resource-only"/>
  <topicref collection-type="sequence" keyref="graphik-import_topic"
            toc="yes" type="topic" xml:lang="de-de">
    <topicref keyref="bitmap-importieren_task" toc="yes"
              type="task" xml:lang="de-de"/>
    <topicref keyref="vektor-importieren_task" toc="yes"
              type="task" xml:lang="de-de"/>
  </topicref>
</map>

user_content.ditamap

Die Map für das Anordnen der Topics zu den Benutzerkonto-Einstellungen sieht analog aus. Auch hier wird nicht direkt verlinkt mit Hilfe eines Pfades plus Datei, sondern einem Schlüssel via keyref.

<map id="user_content" title="Benutzerkonto-Einstellungen" xml:lang="de-de">
  <mapref href="02-technical-reuse/user/user_container.ditamap"
          processing-role="resource-only"/>
  <topicref collection-type="sequence" keyref="user_topic"
              toc="yes" type="topic" xml:lang="de-de">
    <topicref keyref="profil-anlegen_task" toc="yes"
              type="task" xml:lang="de-de"/>
    <topicref keyref="profil-loeschen_task" toc="yes"
              type="task" xml:lang="de-de"/>
  </topicref>
</map>

Container-Maps

Nicht zu verwechseln mit Content-Maps! Content-Maps dienen zur Bestimmung der Reihenfolge bzw. der Anordnung der Topics. Dagegen Container-Maps lediglich dazu dienen, jedem Dateipfad eines Topics (href) einen Schlüssel (keys) zuzuordnen. Auf diese Zuordnung wird in den Content-Maps durch keyref referenziert.

Sämtliche Topics zu den beiden Containern Graphik-Import und Benutzerkonto werden via keydef in eine separate Map gebündelt. Doch am Ende der Topic-Aufzählung erfolgt eine mapref-Referenz! Diese bildet den Dependency Tree ab.

graphik-import_container.ditamap

Die Mapdatei, die die Schlüssel für den Graphik-Import und die dazugehörigen Datei-Verweise auflistet. Mit Dependency Tree (s.u.).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
"http://docs.oasis-open.org/dita/v1.2/os/dtd1.2/technicalContent/dtd/map.dtd">
<map id="graphik-import_container" title="Container Graphik-Import" xml:lang="de-de">
  <keydef href="graphik-import_topic.xml" keys="graphik-import_topic"/>
  <keydef href="bitmap-importieren_task.xml" keys="bitmap-importieren_task"/>
  <keydef href="vektor-importieren_task.xml" keys="vektor-importieren_task"/>
  <mapref href="../../02-technical-reuse/user/user_container.ditamap"/>
</map>

user_container.ditamap

Die Mapdatei, die die Schlüssel für die Benutzerkonto-Einstellungen und die dazugehörigen Verweise auflistet.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
"http://docs.oasis-open.org/dita/v1.2/os/dtd1.2/technicalContent/dtd/map.dtd">
<map id="user_container" title="Container Benutzerkonto-Einstellungen" xml:lang="de-de">
  <keydef href="user_topic.xml" keys="user_topic"/>
  <keydef href="profil-anlegen_task.xml" keys="profil-anlegen_task"/>
  <keydef href="profil-loeschen_task.xml" keys="profil-loeschen_task"/>
</map>

Die obige graphik-import_container.ditamap hat ganz unten einen mapref-Tag. Dagegen die untere user_container.ditamap hat dies nicht. Erstere, die Datei graphik-import_container.ditamap bildet den Dependency Tree für die Publikation “Das Graphik-Importmodul” ab:

Dependency-Tree-Graphik-Import
Layer 6 verlinkt zu 2 aber nicht umgekehrt

Die 3 keydef-Einträge in graphik-import_container.ditamap repräsentieren den Container Graphik-Import auf Layer 6. Der mapref-Eintrag symbolisiert den Pfeil hin zum Container Benutzerkonto-Einstellungen auf Layer 2. Das ist das Geheimnis bei Aufbau eines Dependency Trees: Am Ende einer Container-Map mit seinen keydef-Einträgen kommen die mapref-Einträge der Container, die sich in unteren Layern und natürlich auf den Dependency-Tree befinden!

Links innerhalb der Publikation

Verlinken Sie nun von Layer 6 (Graphik-Import) indirekt via keyref auf eine Seite im Layer 2 (Benutzerkonto), funktionieren diese Links bestens. Hier ein Link in der Datei graphik-import_topic.xml.

<p>Geben Sie in Ihren <xref keyref="user_topic">Benutzerkonto-Einstellungen</xref> die möglichen Graphikformate an.</p>

Verlinken Sie nun umgekehrt von Layer 2 (Benutzerkonto) aufwärts auf Layer 6 (Graphik-Import), werden diese Links einfach nicht aufgelöst! Hier ein Link in der Datei user_topic.xml.

<p>Sie können verschiedene Graphikformate in das Programm <xref keyref="graphik-import_topic">importieren</xref>. Die Auswahl der möglichen Formate treffen Sie in den Benutzerkonto-Einstellungen unter <uicontrol>Graphik-Formate</uicontrol>.</p>

Die Dokumentationen sowohl des Moduls Graphik-Import als auch des Moduls Benutzerkonto-Einstellungen bleibt weiterhin modular. Man kann sie abspalten, mit anderen Dokumentationen verbinden oder auch einzeln ausgeben.

Ads