User-Interface-Texte in der Dokumentation

(Vortrag auf der tekom Jahrestagung 2010, Do 4.11.2010, 9:45 Uhr)

Wenn Software beschrieben wird, hat es ein Redakteur oft mit Hunderten von Bezeichnern aus dem User Interface zu tun, die sich aus den verschiedensten Gründen auch relativ spät noch ändern können. Verschärft wird die Aufgabenstellung durch Übersetzungen, insbesondere wenn der Übersetzer nicht parallel das bereits lokalisierte UI einer Anwendung vorliegen hat. Der Vortrag zeigt anhand konkreter Projektdaten, wie mit FrameMaker (strukturiert) und einem kostenfreien Plug-in eine solide Basis auch für last-minute Updates geschaffen werden kann.

Szenario

Selbst wenn eine Software nur »hunderte« Bezeichner hat, werden diese in aller Regel vielfach in der Dokumentation verwendet, so dass man auf »tausende« Verwendungsstellen kommt. In einer ca. 250-seitigen Dokumentation kam ein Kunde auf ca. 3300 Verwendungen von Begriffen aus dem User Interface. Insofern ist es leicht nachvollziehbar, dass ein recht hoher Druck entsteht, die Texte konsistent zu halten, wenn im Rahmen von Änderungen oder Weiterentwicklungen Begrifflichkeiten geändert werden – oder auch nicht. Auch wenn die Technische Redaktion in die Formulierung des User Interface eingebunden ist (was nicht die Regel darstellt), löst dies nicht das Problem, die Dokumentation diesbezüglich konsistent zu halten.

Die Aufgabenstellung wird multipliziert mit der Anzahl der Fremdsprachen, wobei es auch vorkommt, dass für bestimmte Länder zwar eine übersetzte Dokumentation erstellt wird, die Software aber nicht lokalisiert wird.

Oft werden auch für die Software-Lokalisierung andere Werkzeuge eingesetzt als für die Übersetzungen.

Die Aufgabe besteht also darin, die in einer Dokumentation verwendeten User-Interface-Texte zu beliebigen Zeitpunkten mit den aktuellen Strings aus der Software-Entwicklung zu aktualisieren.

Lösung

Innerhalb der Software ist jeder String bereits mit einer ID versehen, über die er auch verwaltet wird. Das verwendete Lokalisierungs-Tool kann die Strings zusammen mit dieser ID in der Regel im XML-Format ausgeben.


XML-Datei mit IDs und englischen Strings (gekürztes Beispiel)

Die XML-Strukturierung von Dokumentation mit der Möglichkeit Attribute zu verwenden, eröffnet hier effiziente Möglichkeiten, eine Verknüpfung von Dokumentation und extern zugelieferten Strings zu schaffen.

Selbstverständlich lässt sich so eine Verbindung für FrameMaker-Dokumente durch Programmieren einer Schnittstelle herstellen, allerdings gibt es seit einige Jahren das kostenlose Plug-in InsetPlus, welches diesen Prozess tatkräftig unterstützt. Da der US-amerikanische Programmierer des Plug-ins selbst als technischer Redakteur tätig ist, ist die Lösung ausgesprochen praxisnah.

Anwendung

InsetPlus arbeitet mit Verbindungen zwischen FrameMaker-Dateien und lässt sich daher auch für anderer Aufgaben im Rahmen der Wiederverwendung von Texten einsetzen. Zur Einrichtung muss man die gelieferten XML-Dokumente in FrameMaker-Dokumente umwandeln, die der Dokumentation »ähnlich« sind.

Wenn in der Dokumentation das Element <uicontrol> verwendet wird, muss das Dokument mit den Software-Strings gleiche Elemente enthalten. Erstellen Sie ein eigene Strukturapplikation für die Software-Strings, die dann mit einem XSL-Preprocessing die abgebildete XML-Struktur zum Beispiel in folgende FrameMaker-Struktur umbaut:


Struktur einer FrameMaker-Datei mit UI-Strings

Jetzt kann für ein neues Element <uicontrol> der Editor von InsetPlus geöffnet und im Dialog aus der Referenzdatei die gewünschte ID ausgewählt werden.


InsetPlus Editor


Strukturansicht des FrameMaker-Dokuments nach Auswahl eines Strings

Im FrameMaker-Dokument findet sich dann das korrekt ausgefüllte Attribut conref und damit die Basis für spätere Aktualisierungen.

Verfügbarkeit

Das Plug-in kann auf http://www.weststreetconsulting.com/ geladen werden, es kann ab FrameMaker 7 eingesetzt werden und kommt mit Referenz und Tutorial, beides in englischer Sprache. Für November 2010 ist eine deutsche Version des Plug-ins angekündigt.

Ein Kommentar zu User-Interface-Texte in der Dokumentation

  1. Pingback: tekom Jahrestagung 2010 – Rücklick | Die Redakteuse

Kommentare sind geschlossen.