Quanos and Friends in Hamm
Dokuwerk und Quanos Solutions informieren gemeinsam über die neuesten Trends der Technischen Dokumentation.
Zentrale Layout-Funktionen im SCHEMA Page Layout Designer umsetzen
Dieser Artikel zeigt anhand eines Beispiels im SCHEMA Page Layout Designer (PLD), wie der Grundsatz der Wiederverwendung sich auch im Bereich Layout anwenden lässt: die Auslagerung von zentralen Funktionen sorgt für Konsistenz und einen niedrigeren Wartungsaufwand.
Aus dem Bereich der Softwareprogrammierung kommt der Ansatz, möglichst in sich geschlossene, gekapselte Bausteine zu verwenden, die jeweils nur eine Funktion ausführen. Wenn diese Funktion gebraucht wird, kann sie von anderen Stellen aufgerufen werden. Sie übergibt dann das Ergebnis der Verarbeitung zurück an die aufrufende Funktion. Der Vorteil einer solchen Aufsplittung nach Funktionen: Wenn eine Anpassung der Funktion (z. B. eine Erweiterung) notwendig wird, muss nur eine Stelle im Code angepasst werden, egal wie oft die Funktion an anderen Stellen in der Software aufgerufen wird.
Die moderne technische Dokumentation schlägt den gleichen Weg ein. Um Dokumentation wartungsfreundlich zu machen, werden Verflechtungen im Inhalt so weit wie möglich reduziert. Dazu gehören z. B. Hyperlinks und textliche Verweise auf andere Kapitel (im schlimmsten Fall mit nicht automatisch generiertem Text oder Seitenzahlen). Auch Referenzen auf die „Außenwelt“, wie z. B. unnötige Wiederholungen von Produkt- oder Firmennamen, sollten vermieden oder weitgehend reduziert werden.
Diesen Ansatz übertragen wir auf das Arbeiten mit Layouts im PLD:
Angepasste Layoutstrecken basieren in der Regel auf dem Standardlayout, das mit ST4 geliefert wird. In diesem Standardlayout werden Layoutelemente für verschiedene Seitensequenzen definiert, z. B. Titelblatt, Inhaltsverzeichnis, Inhalt rechte Seite, Inhalt linke Seite, Rückseite. Dabei gibt es Layoutelemente, die sich in mehreren Sequenzen wiederholen können. So hatten wir z. B. in einem Projekt ein Layout, in dem an acht verschiedenen Stellen ein Zeitstempel ausgegeben werden sollte.
Praxisbeispiel: zentrales Datumformat
Eine typische Layoutanpassung für einen Kunden besteht darin, das Format des Zeitstempels kulturraumspezifisch anzupassen (z. B. „DD-MM-YYYY“ für den europäischen Markt vs. „YYYY-MM-DD“ für den US-amerikanischen Markt). Hierfür wird im PLD-Layout die verwendete Dokumentsprache abgefragt und das Format entsprechend ausgegeben. Diese Abfrage muss im PLD an besagten acht Stellen jeweils 2x parallel eingebaut werden. Wenn später eine weitere Sprache dazukommt, muss die Abfrage an diesen 16 Stellen konsistent angepasst werden. Dabei passiert es leicht, dass eine Stelle vergessen und das Datum dann in einer Fremdsprache an einer Stelle im Dokument falsch angezeigt wird.
Um dies zu vermeiden, lagern wir bestimmte Layoutregeln an eine zentrale Stelle aus, um sie aus unterschiedlichen Kontexten aufzurufen. Am Beispiel der Definition des Datumformats geht man wie folgt vor:
Schritt 1: Im SCHEMA PLD unter Inhaltslayout/Processing Rules eine neue Gruppe „generateDate“ anlegen, die die neue Funktion enthalten wird. Die Processing Rules liegen an einer anderen Stelle als die regulären Layoutregeln und enthalten generische Regeln, die publikationssequenz-übergreifend sind.
Wir wissen nicht, aus welchem Element oder Kontext heraus die Datumsfunktion aufgerufen wird, deshalb bekommt die neue Gruppe „generateDate“ einen generischen Selektor (Auswahl: „*“). Um sie von der übrigen Verarbeitung zu trennen, wird sie dafür in einem eigenen Modus (Modus: „generateDate“) angesteuert.
Schritt 2: Innerhalb der neuen Gruppe zwei Elemente anlegen, die die beiden möglichen Datumsformate erzeugen. Jedes Datumsformat bekommt eine Abfrage der verwendeten Sprache, sodass bei der Publikation jeweils nur ein Datumformat ausgegeben wird (Bedingung: „ancestor-or-self::node[@aspect-name = 'de' or @ aspect-name = 'fr']“
Schritt 3: Alle Stellen im eigentlichen Layout, an denen ein Datum erzeugt werden soll, durch eine generische Referenz auf die zentrale Datumsfunktion ersetzen. Dies geschieht durch eine Weiterverarbeitung (Auswahl: „.“) im richtigen Modus (Modus: „generateDate“):
Ergebnis: statt 8 Stellen und damit 16 Abfragen der Sprache im Layout gibt es nur noch eine Stelle, die beim Hinzufügen neuer Sprachen oder Änderungen am Datumsformat angepasst werden muss.
Dies ist nur ein möglicher Ansatz unter vielen, um Layouts zu vereinfachen. Haben Sie Fragen oder Anregungen zum Thema, schreiben Sie uns. Wir freuen uns auf Ihre Nachricht.