Wenn Sie Software-Dokumentationen erstellen, kennen Sie das bestimmt: Eine ganz besondere Herausforderung für Redakteure ist der Abgleich von Oberflächenbezeichnungen zwischen Software und der Technischen Dokumentation. Denn ändert sich die Bezeichnung eines Oberflächenelements in der Software, muss das in der Dokumentation nachgezogen werden. Gleiches gilt für einstellbare Werte auf der Softwareoberfläche, auch sie werden oft noch kurz vor Entwicklungsschluss verändert. Bei unterschiedlichen Versionen der Software und damit auch der Dokumente, ist das Nachpflegen der Veränderungen ein aufwändiger Schritt, der oft einem eigenen Redaktionsprozess gleicht.
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.
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 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:
Für jede der Anforderungen wurde eine eigene Schnittstelle entwickelt, die wir uns jetzt jeweils an einem Beispiel genauer ansehen.
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.
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.
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, 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.
Stellen Sie sich vor, Ihr Unternehmen würde Heizlüfter herstellen. Draußen wird es langsam Winter und Sie wissen, das…
Wenn Sie als Unternehmen Ihre Produkte weltweit verkaufen, benötigen Sie fast automatisch eine mehrsprachige Dokument…
Fast immer hilft es, wenn man miteinander spricht. Chatbots können auf Seiten eines Serviceanbieters eine gute Möglic…