Ein weiterer sehr wichtiger Aspekt einer guten Dokumentation ist die klare Definition und Verwendung von Begriffen – fachlich und technisch. In einem komplexen Umfeld kommt es sehr oft zu der Situation, in denen wir unterschiedliche Ausdrücke für den gleichen Begriff in der Systembeschreibung verwenden, um damit unterschiedliche Zielgruppen besser zu erreichen.

05 Wieso benötigen wir eindeutige Begriffe

In der technischen Umsetzung müssen wir uns jedoch für einen Begriff entscheiden. Bei der Wahl der Begriffe ist es wichtig, die Sprache der Nutzer des Systems und der Fachabteilungen zu berücksichtigen.

Glossar für alle Begriffe

Das Problem des “Überladens” von Begriffen bekommen wir durch die Einführung eines Glossars in den Griff. Wichtig ist aber, dass dieses Glossar vor allem von den Stakeholdern konsequent verwendet wird. Das ist nicht immer leicht, weil es oft regionale Unterschiede bei der Bezeichnung von Begriffen in den verschiedenen Fachabeilungen gibt (z.B. Ereignis).

Ein sehr gutes Beispiel aus der Domäne eines Eisenbahnverkehrsunternehmen ist der Begriff Ereignis. Ein Ereignis ist sehr oft mit einem Problem verbunden, z.B.

  • eine Störung im Betriebsablauf (z.B. eine Strecke ist gesperrt),
  • ein Konflikt in der Verwendung eines Fahrzeuges,
  • ein Problem im Dienstplan eines Personals,
  • eine Mitteilung über eine Fahrzeugstörung oder
  • die Meldung einer Verspätung.

Weitere Ereignisse sind beispielsweise

  • die Meldung einer Fahrzeugposition (z.B. mit GPS),
  • der planmäßige Dienstantritt eines Personals,
  • die Verfügbarkeit eines neuen Tagesfahrplanes oder
  • betriebsbedingte Nachrichten.

Alle hier aufgezählten Ereignisse sind Auslöser für Prozesse. Allerdings sind es verschiedene Prozesse mit unterschiedlichen Auswirkungen.

Das Projekt muss trotz der immer wieder massiv auftretenden Widerstände darauf drängen, dass sich alle Fachabteilungen auf einen Begriff im Glossar festlegen. Und der beste Weg, die Fachabteilungen auf den Begriff “einzuschwören” ist die konsequente Nutzung der Begriffe in allen Workshops mit den Auftraggebern, Fachabteilungen und Nutzern und in der Systembeschreibung.

Das Glossar ist ein wichtiger Teil der Systembeschreibung und muss aktiv gepflegt werden.

Darum müssen wir bereits am Beginn der Analyse einer fachlichen Anforderung die elementarsten Begriffe (englisch: buzzwords) identifizieren und sofort im Glossar erfassen. Die konsequente Nutzung dieser Begriffe aus dem Glossar wird durch konsequentes Feedback der Leser sichergestellt.

Begriffe konsequent nutzen

Bei der Verwendung eines Wiki zur Dokumentation empfehlen wir, die Begriffe konsequent mit dem Glossar zu verlinken. Die Vorteile dieser Praxis sind:

  1. Durch den Link hebt der Autor einen Begriff automatisch hervor.
  2. Der Leser kann sich sofort den Begriff erklären lassen durch Klick auf den Link.
  3. Es gibt die Möglichkeit, alle Seiten zu suchen, die exakt diesen Begriff enthalten.

In einem Wiki hat diese Praxis außerdem den Vorteil, dass der verlinkte Begriff automatisch korrigiert wird, wenn der Eintrag im Glossar umbenannt wird.

Keine Übersetzung der Begriffe

In großen Projekten kommt es immer wieder vor, dass Dienstleistungen komplett oder teilweise ausgelagert (englisch: nearshore oder offshore outsourcing) werden. Schnell entsteht der Bedarf für Übersetzungen, in der Regel in die englische Sprache. Das bedeutet für das Glossar, dass ein zweiter Begriff in dieser Sprache notwendig wird. Diese Übersetzungen müssen sorgfältig gewählt werden. Schnell schleicht sich der eine oder andere Begriff ein, der englisch klingt, aber in der Form keine korrekte Übersetzung oder nicht einmal ein englisches Wort ist. Das Wort Handy für Mobiltelefon ist ein bekanntes Beispiel. Außerdem lassen sich Begriffe oft nicht vollkommen eindeutig übersetzen oder es gibt keine direkte Übersetzung, eine Umschreibung ist notwendig.

Selbst bei einer “perfekten” Übersetzung entsteht oft ein “Bruch” in der Bedeutung eines Begriffes durch kulturelle Unterschiede.

Eine Vorgabe in unserer Dokumentenstruktur ist, wichtige Begriffe der fachlichen Domäne nicht zu übersetzen. In unserem Fall ist die Sprache der Domäne deutsch! Wir stellen als Lesehilfe eine in jeder Projektsprache (hier deutsch und englisch) für alle Projektmitarbeiter verfügbaren Glossar zur Verfügung. Sowohl für Übersetzungen als auch beim Programmieren gibt es die Vorgabe, dass Begriffe der Domäne aus dem Glossar in Texten und Kommentaren und für Bezeichner von Klassen, Attributen und Operationen nicht übersetzt werden. Dieses Vorgehen führt zu einem Sprachenmix, den aber alle Beteiligten nach meiner Erfahrung sehr schnell beherrschen.

Wichtige Begriffe der Domäne sind allen Projektmitgliedern unabhängig von der Sprache im Team ein fester Begriff.

Das Ziel, im Projekt in einer gemeinsamen Sprache zu sprechen, erreichen wir durch diese Vorgabe besser als mit der besten Übersetzung – ganz abgesehen davon, dass wir es nicht immer schaffen, die Übersetzung in der besten Qualität zur Verfügung zu stellen.

Nehmen wir doch ein konkretes Beispiel aus der Domäne eines Eisenbahnverkehrsunternehmen: Die Betriebslage ist die Menge der Verkehrsmittel, die

  • in den nächsten 60 Minuten planmäßig von ihrem Startort abfahren,
  • aktuell unterwegs sind oder
  • seit weniger als 30 Minuten am Zielort angekommen sind.

Mit anderen Worten umfasst die Betriebslage genau die Verkehrsmittel, die der Disponent in unserem System überwachen muss.

Nehmen wir folgenden Satz an:

Die Fahrgäste müssen also jederzeit über die aktuelle Betriebslage informiert sein.

Ein erster Versuch führt zu dieser Übersetzung:

What we can take from this is that passengers need to be kept up to date on the latest developments at all times.

Das ist bestenfalls ein Umschreibung, aber weit weg von einem klaren Begriff, wie es das Wort Betriebslage ist.

Eine in unserer Dokumentation gültige Übersetzung lautet:

What we can take from this is that passengers need to be kept up to date on the Betriebslage at all times.

Verhindern wir die Übersetzung von wichtigen Begriffen der Domäne, dann werden sie eingebettet in der fremden Sprache automatisch hervorgehoben. Die Übersetzung oder oft auch Umschreibung des Begriffes in allen Projektsprachen befindet sich im Glossar.

Fazit

Eindeutige Begriffe sind ein wesentlicher Erfolgsfaktor für die Qualität der Produktdokumentation. Das Glossar ist ein ganz wichtiger Bestandteil. Es muss aktiv gepflegt werden, solange Erweiterungen am Software-Produkt vorgenommen werden.

Es ist nicht leicht, eindeutige Begriffe in einem Projekt und letztendlich auch im Code durchzusetzen. Aber was ist die Alternative?