Der Reise-Butler ist die Smartphone-App für den wissbegierigen Reisenden und Fallbeispiel für die Methode CARDS+.


Nach der Einrichtung des Bereiches für die Produktdokumentation des Reise-Butlers in Confluence beginnt Moritz mit dem Glossar. Es ist ein wichtiger Teil der Methode CARDS+ und soll gleich zu Beginn angelegt und kontinuierlich fortgeführt werden. Moritz fängt mit den offensichtlichen Begriffen an. Beim Reise-Butler geht es um eine Reise. Klar. « Ist der Nutzer der App ein Reisender, Fahrgast oder Passagier? », fragt er sich. Moritz entscheidet sich für Fahrgast. Er lässt sich besser vom Begriff Reise unterscheiden, hat einen Bezug zu Fahrplan bzw. Fahrt und ist nicht so sperrig wie Passagier.

Beim Schreiben stellt er fest, dass es gar nicht so einfach ist, jeden Begriff prägnant und korrekt zu beschreiben. Viele Begriffe haben mehr als eine Bedeutung. Ein wichtiges Ziel des Glossars ist es, Klarheit in die Begriffe zu bringen.

Moritz schaut sich den Begriff an, mit dem er begonnen hat: Der Fahrgast. Die Erklärung besteht gerade mal aus zwei Sätzen. In diesen zwei Sätzen stecken aber eine ganze Reihe weiterer Begriffe: Fahrzeug, Verkehrsmittel, Personal, Verkehrsunternehmen. Für jeden weiteren neuen Begriff legt er eine Seite im Glossar an und schreibt sofort einen Satz dazu. Dadurch kann er die einzelnen Beschreibungen auf das Wesentliche beschränken. Er braucht nicht jeden Begriff, den er erwähnt, immer wieder aufs Neue erklären, sondern hinterlegt jeden wichtigen Begriff mit einem Link zur entsprechenden Seite im Glossar. Mit diesem Vorgehen vermeidet er automatisch mehrfache Beschreibungen eines Begriffes. Er bleibt konsistent in seiner Beschreibung.

Ein Punkt ist Moritz wichtig: Er will eindeutige Begriffe. Für den Begriff Fahrgast gibt es aber zwei weitere Begriffe: Passagier und Reisender. Diese Begriffe trägt er zusätzlich zum Begriff Fahrgast als Stichworte der Seite ein. Für die Begriffe Passagier und Reisender legt er aber keine Seite an. Das Glossar baut er so auf, dass es für jeden Buchstaben im Alphabet eine eigene Seite gibt. Die beiden Buchstaben X und Y fasst er zusammen. Begriffe, die mit einer Ziffer beginnen, fasst er ebenfalls zusammen. Jeder dieser Übersichtsseiten zeigt eine Liste aller Begriffe, die diesen Anfangsbuchstaben haben.

Das Confluence-Makro »Seitenhierarchiesuche« (»Page Tree Search«) bildet den Einstieg in das Glossar. Die Suche ist beschränkt auf das Glossar und seine Unterseiten. Auf der Startseite befindet sich ein kurzer Hilfetext, der die Pflege des Glossars erläutert. Am rechten Rand befinden sich die zuletzt angelegten oder geänderten Einträge im Glossar.

Das Suchergebnis listet Seiten auf, die den gesuchten Begriff im Titel oder Text enthalten. Auch alternative Schreibweisen wie der Plural erkennt Confluence. Mit wenigen Klicks kann ein Suchergebnis noch weiter eingeschränkt werden, z.B. nach dem Autor oder einem Zeitraum.

Diese Übersicht zeigt alle Begriffe im Glossar, d.h. alle Seiten mit dem Stichwort »term«. Mit der Confluence-Funktion »Zugehörige Stichwörter« (»Related Labels«) kann die Übersicht durch Kombination der Stichworte weiter verfeinert werden.

Im Glossar gibt es für jeden Buchstaben eine Übersichtsseite. Das Confluence-Makro »Inhalte nach Stichwort« (»Content By Label«) zeigt nur Unterseiten dieser Übersichtsseite. Für jeden Glossareintrag wird die Definition angezeigt, die mit dem Confluence-Makro »Auszug«  (»Excerpt«) festgelegt wird.

Schnell stellt Moritz fest, dass Confluence bei der Eingabe von Links so gewisse Tücken hat. Durch schnelles “copy & paste” aus der Leseansicht werden Links zu externen Web-Links, um nur ein Problem zu nennen. Das ist nicht gut. Zum Abschluss der Bearbeitung einer Seite wirft Moritz darum immer einen kurzen Blick auf die Seiteninformation. Er prüft, ob alle Links in dieser Seite plausibel sind. Diese kleine Aufmerksamkeit kostet ihn nur wenig Zeit. Sie hilft aber, die Qualität der Inhalte zu erhöhen.

Die Liste der abgehenden Links in den «Seiteninformationen» («Page Information») zeigt, welche anderen Informationen in der vorliegenden Seite relevant sind. Confluence unterscheidet externe und interne Links.

Die Liste der ankommende Links in den «Seiteninformationen» («Page Information») zeigt, wo die vorliegende Seite eine Rolle spielt, also entweder im Text verlinkt oder als Seite eingebettet wurde.

Im Verlauf der weiteren Analyse wird Moritz die Begriffe noch weiter verfeinern, manche sogar in ihrer Bedeutung schärfen. Er ist überzeugt, dass eindeutige Begriffe wichtig sind. Sie führen zu einer gemeinsamen Projektsprache. Konsequente Nutzung der Begriffe aus dem Glossar helfen bei der Vermeidung oder Erkennung von Widersprüchen in den Bausteinen der Systembeschreibung. Nur so kann der Aufwand für die Pflege der gesamten Produktdokumentation dauerhaft gering bleiben, bei gleichbleibend guter Qualität.

Zuletzt veröffentlichte Beiträge: