Automatische Konsistenz zwischen Dokumentation und Entwicklung? - BIOTRONIK zeigt, wie es geht

BIOTRONIK hat zusammen mit SCHEMA nach einer möglichst komfortablen Lösung gesucht und sie in einer individuellen Anpassung gefunden. In einem gemeinsamen Projekt wurden zwei Schnittstellen definiert, die für die versionsgenaue Konsistenz der Bezeichnungen sorgen sollen.

Auf der SCHEMA Conference im Juni 2018 hat uns Alexandra Koegstadt als Technische Redakteurin und Teilprojektleiterin die beiden Schnittstellen vorgestellt und berichtet, wie das Projektteam mit der „komplexen Anforderungslage“ umgegangen ist.

Auf der Suche nach einer komfortablen Lösung für höchste Präzision

BIOTRONIK ist eines der führenden Unternehmen für kardiologische Medizintechnik mit Hauptsitz in Berlin und setzt das XML-Redaktionssystem SCHEMA ST4 seit 2017 an 3 Standorten für die Technische Redaktion ein. Sie produzieren unter anderem Herzschrittmacher, Defibrillatoren und externe Geräte zur Elektrotherapie des Herzens. Eine hohe Qualität der Dokumentation muss in dieser Branche gewährleistet sein. Ein Arzt, der zum Beispiel die Grundfrequenz eines Herzschrittmachers einstellen soll, braucht eine präzise Anleitung. Stimmen Benennungen nicht überein, können bei solch sensiblen Einsätzen große Risiken und rechtliche Konsequenzen entstehen. Ziel der Technischen Redaktion bei BIOTRONIK war also, automatisiert die bereits vorhandenen Benennungen aus Entwicklungs-Datenbanken zu verwenden, um eine hohe Qualität und Konsistenz zu erhalten.

Die Anforderungen und die Lösung

Die Lösung kam in Form neu entwickelter Schnittstellen zwischen ST4 und den BIOTRONIK Entwicklungsdatenbanken. Dadurch werden Benennungen in der Dokumentation automatisch aktualisiert, sobald diese in der Datenbank aktualisiert werden - ohne weitere Handarbeit.

Für diese Inhalte musste der Abgleich automatisch möglich sein:

• Oberflächenelemente wie GUI-Strings, die in den Dokumentationen zitiert werden müssen.
• Parameter-Werte, die GUI-Strings zugeordnet sind.

Für jede der Anforderungen wurde eine eigene Schnittstelle entwickelt, die wir uns jetzt jeweils an einem Beispiel genauer ansehen.

Schnittstelle 1: Oberflächen-Benennungen direkt in ST4 integrieren

Als Erstes sollen die zitierten Oberflächenelemente in der Dokumentation mit den GUI-Bezeichnungen in der Software übereinstimmen - und das in allen Sprachen.
Ein Beispiel: Das Oberflächenelement „Grundfrequenz“ soll in der Dokumentation immer der GUI-Bezeichnung in der Softwareoberfläche entsprechen:

Dafür wurde die erste Schnittstelle geschaffen: Eine Verbindung zwischen dem CMS ST4 und der Datenbank, in der die Bezeichnungen der GUI-Elemente (dort als „GUI-Strings“ vorliegend) abgelegt sind.

Wie geht der Redakteur nun für den automatischen Abgleich vor?

Der erste Schritt ist, die ID des GUI-Elements in der Software herauszufinden. Dafür verwenden die Redakteure ein BIOTRONIK-eigenes Tool. Die ID wird anschließend in ST4 in den Editor eingegeben und mit einem speziellen Inline-Element ausgezeichnet.

Übersetzung inklusive

Das besondere Plus: In der GUI-String-Datenbank von Biotronik werden Inhalte bereits mehrsprachig gepflegt. Das senkt die Übersetzungskosten und erhält gleichzeitig die Konsistenz.

Mithilfe des Metadatums „Checkpoint“ wird die Zuordnung zur jeweiligen Software-Version gewährleistet. Ändert sich also ein GUI-Element in einer aktuelleren Version oder einer Variante, wird dies auch in der Dokumentation nur für diese Version übernommen.

Mit der Veröffentlichung des Projekts werden alle GUI-Zitate mit dem festgelegten Checkpoint ausgeleitet - „egal, wie oft sich der GUI-String oder die Übersetzung in der Zwischenzeit nochmal verändert hat“, erklärt Frau Koegstadt.

Schnittstelle 2: Parameter-Werte aus der Datenbank in ST4 integrieren

Eine zweite Schnittstelle soll die Konsistenz beim Zitieren von Parameter-Werten garantieren. Diese Werte liegen nicht in der GUI-String-Datenbank, sondern in einer eigenen Parameter-Werte-Datenbank. Für die Redakteure ändert sich am Vorgehen zur GUI-String-Schnittstelle allerdings nur wenig.

Kurz zum Beispiel von oben, um zu verstehen, was ein Parameter-Wert ist: Die Grundfrequenz eines Herzschrittmachers liegt in einem bestimmten Wertebereich, der über einen Standardwert zusammengefasst wird. Der Standardwert der Grundfrequenz lautet zum Beispiel „60“. Der dahinterliegende Wertebereich aber „30 (5) 100 (10) 160bpm“.

„Grundfrequenz“ liegt also als Oberflächenelement in der GUI-String-Datenbank, die dazugehörigen Einstellmöglichkeiten als Parameter-Werte in der Parameter-Werte-Datenbank.
Schauen wir uns auch hier kurz an, wie die Redakteure den Abgleich dank der zweiten Schnittstelle vornehmen.

Zunächst haben die Parameter aus der Software wieder eine eigene ID (Parameter-ID), die über das interne Tool identifiziert werden kann - also genau wie bei den GUI-Strings. Die Parameter-ID wird ebenso wieder im ST4-Editor erfasst und mit einem Inline-Element ausgezeichnet:

Der Unterschied zur Schnittstelle 1 ist: Da sich die Parameter-Werte pro Produkt-Projekt unterscheiden können, muss eine präzise Abfrage der Werte in ST4 möglich sein. Um für die Produktvariante die richtigen Werte in der Dokumentation abzubilden, müssen folgende Details zum Parameter angegeben werden: Produkt-Projekt, Verkaufsgebiet, Produkt-Feature-Set und Produkt-Typ.

Dank Parameter-ID und spezifischer Abfrage für das Produkt-Projekt werden die Parameter-Werte sauber in die Datenblätter und Gebrauchsanweisungen eingefügt. Auch hier sehen die Redakteure während der Laufzeit die Werte bereits in der Schnellansicht. Die Tabellen sind je nach Dokumentart anpassbar. In den Datenblättern können einzelne Spalten entfernt werden, die dort nicht relevant sind.

Nach dem Einfügen der Parameter-ID werden noch die relevanten Metadaten gesetzt, anschließend wieder der Checkpoint hinterlegt, ein Filter gesetzt und das Projekt produziert.

Das Ergebnis sieht dann so aus:

Die Texte in den Spalten stammen allein aus dem automatischen Abruf der Werte aus den beiden Datenbanken.

Lessons Learned

Was im Nachhinein einfach klingt, war in Wirklichkeit ein Entwicklungsprojekt mit sehr komplexen Anforderungen. In einem iterativen Vorgehen fanden die BIOTRONIK-Redakteure und die SCHEMA-Consultants aber eine Lösung, deren Mehrwert auch auf lange Zeit bestehen bleiben wird.

So wurde nicht nur das Hauptziel erreicht, die Konsistenz ohne manuelles Nachprüfen zu gewährleisten. Es konnten auch zusätzlich die Erstellungszeit der Dokumentation gesenkt und Übersetzungskosten eingespart werden.

Alexandra Koegstadt

Alexandra Koegstadt, Berlin, Diplom-Medienberaterin und Technische Redakteurin, seit 2007 tätig für BIOTRONIK SE & Co. KG (Medizintechnik), Teilprojektleiterin für die Bereitstellung eines neuen Redaktionssystems am Standort Berlin; ST4 wird an 3 Standorten seit Mitte 2017, bzw. Anfang 2018 mit Standort-spezifischen Erweiterungen produktiv eingesetzt.