Ein Angebot von

Software-Dokumentation in der Praxis

| Autor / Redakteur: Mirco Lang / Stephan Augsten

Wenn Text-Schreiber auf Software-Entwickler und deren gewohnte Tools und Entwicklungsumgebungen treffen, prallen oft zwei grundsätzlich unterschiedliche Welten aufeinander. Wie lässt sich so eine praxistaugliche Methode für anständige Software-Dokumentation finden?
Wenn Text-Schreiber auf Software-Entwickler und deren gewohnte Tools und Entwicklungsumgebungen treffen, prallen oft zwei grundsätzlich unterschiedliche Welten aufeinander. Wie lässt sich so eine praxistaugliche Methode für anständige Software-Dokumentation finden? (Bild: gemeinfrei / Pixabay)

Für den Job eines Autors genügen meist ein Texteditor, ein Browser und ein Screenshot-Tool. Der Workflow beschränkt sich auf E-Mails und ein paar Ideen zum Inhalt wären auch nicht schlecht. Aber Dokumentation? Das Schreiben eines Handbuchs für eine komplexe Software? Da kann ich Ihnen ganz andere Geschichten erzählen.

Über das Schreiben von Dokumentationen gibt es viele hilfreiche Texte. So befasst sich etwa auf Dev-Insider.de die Reihe „Software-Dokumentation“ von Christian Rentrop mit dem Thema. Ich selbst arbeite freiberuflich an dem Handbuch einer großen, weltweit vertriebenen Open-Source-Software mit – und war dann bisweilen doch etwas verwundert, was da so auf mich zukam.

Als freier Journalist hat man in der Regel nichts mit dem komplexen Monster namens Git zu tun, muss nicht in Quelltexten stöbern oder gar Screenshots in einem Maße verändern, dass der Begriff „Fake News“ für sie noch ein Euphemismus wäre. Ein paar Eindrücke aus der Welt eines Handbuchschreiberlings möchte ich hier mit Ihnen teilen.

Professionelles Handbuchschreiben

Als Autor musste ich mich daran gewöhnen, derart direkt mit Entwicklern zusammenzuarbeiten – denn hier stammt das Handbuch noch direkt von technischen Consultants und Codern. Und natürlich haben Entwickler ihren eigenen Kosmos an Tools und Workflows. Einen ganz, ganz anderen als Autoren. Ein – aus gewissen Blickwinkeln – technisch unterbelichteter, OpenOffice nutzender Autor kommt da zunächst ins Stocken.

Plötzlich musste ich mich mit Git beschäftigen, eine eigene Markup-Syntax lernen, klar definierten Workflows auf Dateiebene folgen, Tickets herumschubsen, Texte zum Review schicken, eine Handvoll Skripte für diverse Kontrollen auf die Tausenden von Dateien loslassen, Quelltexte studieren, Release Notes lesen und wahnwitzig komplexe Szenarien für Screenshots nachstellen. Die Screenshots werden später noch zum Albtraum.

Und warum das Ganze? Nun, ich würde zweierlei Dinge sehen: Zum einen ist ein Handbuch eine komplexe Angelegenheit. Schließlich arbeiten mehrere Leute an einem mehrsprachigen Buch über ein Produkt, das sich ständig ändert. Zum anderen: Entwickler entwickeln eben – nicht nur Quell-, auch Menschentexte. Habe ich schon erwähnt, dass für Website-Handbuch und gedrucktes Handbuch ein und derselbe Korpus herhalten muss? Das macht es nicht gerade einfacher.

Technischer Rahmen

An der Spitze der Arbeitsverteilung steht wie so oft das Ticketsystem, in dem Arbeitspakete auf Abarbeitung warten – um dorthin zu kommen, muss aber zunächst die VPN-Verbindung stehen. Auf einem zuvor umfangreich einzurichtenden Linux natürlich. Einmal ein Ticket an mich gerissen, kann die eigentliche Arbeit beginnen – bald zumindest.

Wichtigste Grundlage des Ganzen ist zweifellos Git. Die Versionsverwaltung ist bei Entwicklern omnipräsent und ein wirklich tolles Werkzeug. Aber für Autoren? Zum Verwalten von Menschentexten? Nun, auch da macht es einen guten Job.

Allerdings hat es viele, viele Stunden gedauert, bis genügend Grundvertrauen in meine Git-Kenntnisse vorhanden war, um nicht jedes Problem mit einem beherzten „rm -r *“ gefolgt von „git clone“ zu umschiffen. Nun beginnt ein Arbeitstag eben nicht mehr mit dem Abruf der Mails in Thunderbird, sondern mit „git pull“, gefolgt vom Lesen des Logs im Terminal. Dann kann es an Texte gehen.

Texte erstelle ich als Autor gewöhnlich mit Notepad++ oder OpenOffice unter Windows. Entwickler arbeiten aber nun einmal unter Linux und mit vim, emacs & Co. Bei beiden bin ich raus. Beide sind super, wenn man sie immer nutzt, aber nur ab und zu? Da würde es wohl Jahre dauern, bis die Handhabung sitzt.

Also nutze ich Leafpad, einen super simplen grafischen Texteditor. Nun setzen vim- und emacs-Editor fixe Zeilenlängen, in Leafpad muss ich das manuell per ENTER erledigen – und harte Umbrüche an anderen Orten zu setzen als dort, wo ein neuer Absatz entstehen soll, muss auch erst mal in Fleisch und Blut übergehen. Kleinkram, aber wichtig.

Einen Text erstellen und sichten (lassen)

Git als Arbeitsumgebung für Autoren? Das fällt wohl unter „Entwickler-nahes“ Arbeiten.
Git als Arbeitsumgebung für Autoren? Das fällt wohl unter „Entwickler-nahes“ Arbeiten. (Bild: Lang / Git)

Der Text selbst hat auch seine Besonderheiten: Viele selbst entwickelte Makros summieren sich zu einer Art Mini-Markup-Sprache, um Bilder zu setzen, Text auszuzeichnen oder Dinge wie Quelltexte und Auszüge aus Terminal-Sitzungen zu formatieren, die Artikelstruktur aufzubauen oder auch Metadaten wie Status und Datum zu setzen.

Fertige Texte müssen natürlich auch im fertigen Layout gesichtet werden. Dazu kommt ein Skript zum Einsatz, das kurz gesagt lokal einen Webserver startet, die Daten aus dem Git-Repo einspielt und so eine lokale Variante des Online-Handbuchs zaubert.

Wenn der Text fertig ist, kann er im einfachsten Fall mit Git veröffentlicht werden. Wenn er ins Review soll, muss er jedoch erst über das Ticket- oder in einigen Fällen das Review-System erneut in den Workflow geschubst werden. Was dann ein paar Runden branchen, mergen und rebasen mit sich bringen kann.

Sie sehen: Im Gegensatz zum „normalen“ Autoren-Setup verlangt so ein Entwickler-Setup bisweilen wesentlich mehr „Spaß an Technik.“ Und es wird noch mehr folgen.

Inhaltliche Besonderheiten

Beim Inhalt gibt es einige Besonderheiten, die die Arbeit schon sehr weit ab vom normalen Schreiben von Zeitschriftenartikeln bringen. Das beginnt schon mit den Übersetzungen. Das Handbuch muss eben auch auf Englisch verfügbar sein, folglich sieht der Workflow den Weg zum Übersetzer vor.

Was aber, wenn jemand zum Beispiel ein kleines Update in der deutschen Version vornimmt, nicht aber in der englischen Version? Auch hier greift im Hintergrund ein cleveres Gefüge aus Skripten und Auszeichnungen: Über bestimmte Commit-Messages und Skripte lassen sich Übersetzungslücken herausfinden – und fehlende Commit-Messages nachtragen.

Die bisweilen wohl größte Herausforderung: Wo kommen die Inhalte her? Schließlich geht es in der Regel um Inhalte, die sonst nirgendwo im Netz zu recherchieren sind. Vieles lässt sich zum Beispiel aus den Release Notes der einzelnen Patches entnehmen und ab und an muss auch mal ein Blick in den Quellcode her, soweit das für einen Nicht-Entwickler etwas hergibt. Vor allem ist es aber die Kommunikation mit den einzelnen Entwicklern, die beim Handbuchschreiben unerlässlich ist. Sowie natürlich: Testen, testen, testen.

Die Handbuchentwicklung ist aber inhaltlich vor allem eines, nämlich Detailarbeit. Oft geht es eher darum, die vielen kleinen Updates der Coder im Blick zu haben und im Handbuch entsprechende kleine Anpassungen durchzuführen. Und insbesondere: Wirklich sauber zu arbeiten.

Das gilt auch für ein ordinäres Tutorial in einem Blog, eine Anleitung mit Fehler in Schritt 20 nervt. Aber vom Original-Handbuch aus verbreiten sich Fehler natürlich viel schneller bei Anwendern und auch fremden Autoren – nach dem Motto: Der Hersteller muss es ja wissen! Zudem sehen zahlende Kunden ein Handbuch auch sicherlich als Teil der Leistung an.

Die Crux mit dem Druck

Eine Textbasis für Online und Druck? Verlage dürften da auf monolithische, kostspielige Content-Systeme setzen. Als Software-Entwickler hat man natürlich andere Möglichkeiten, wie die besagten Textauszeichnungen in Kombination mit weiteren Skripten. Dass sich der Teufel dann in Details wie im Browser automatisch umgebrochenen Zeilen versteckt oder aber in Tabellen – das scheint einleuchtend.

Am Ende habe ich aber noch einen besonderen Favoriten, der wohl am besten zeigt, warum das Erstellen eines (gedruckten) Handbuchs mitunter wirklich nicht mehr viel mit meinem sonstigen beruflichen Treiben gemein hat: Wenn ich für einen Blog oder eine Zeitschrift einen Screenshot benötige, lichte ich einfach das ganze Fenster oder einen Ausschnitt ab, fertig.

Im Handbuch wird aber viel über die textlastigen Screenshots erklärt – und darum soll die Schrift in den Bildern dieselbe Größe haben wie der Text drumherum. Vor allem im gedruckten Buch sieht zu große Schrift schrecklich aus, zu kleine Schrift ist nicht lesbar – und Anklicken ist auf Papier einfach noch nicht drin.

Folglich muss jeder Screenshot bei maximalem Zoom der Oberfläche erstellt, dann pixelgenau die Größe eines Buchstabens gemessen und anschließend das ganze Bild gemäß einer Größentabelle auf richtige Breite getrimmt werden. Und jetzt versuchen Sie mal, ein 2.500 Pixel breites Bild von einer GUI auf sagen wir 1.200 Pixel Breite zu reduzieren – ohne es herunter zu skalieren, die Ränder zu beschneiden und ohne wichtige Inhalte zu verlieren. Es ist wirklich faszinierend, wie viel Arbeit man in Screenshots stecken kann.

Lohnt es sich?

Was Technik, Workflow und Grafikarbeit angeht, gibt es beim Handbuchschreiben also allerlei Obskuritäten – kann es jedenfalls. Zumindest habe ich sie auch nach über 20 Jahren IT- und gut 15 Jahren Journalistenerfahrung als solche empfunden. Allerdings nur eine Zeit lang: Der Aufwand für Automation und vor allem Details lohnt sich, schließlich ist ein Handbuch auch ein Aushängeschild, ähnlich wie das Schaufenster beim Einzelhändler. Und nebenbei spart es Support-Anfragen ein!

Wie oft habe ich mich schon im Restaurant bei der Lektüre der Karte gefragt: Wenn die ihre Karte nicht ohne etliche Rechtschreibfehler hinbekommen, darf ich dann davon ausgehen, dass sie beim Kochen genauso schlunzig vorgehen? Und genauso sieht es auch bei der Dokumentation aus – Aufwand für Handbücher ist eine verdammt gute Sache!

So geht richtige Anwendungsdokumentation

So geht richtige Anwendungsdokumentation

04.12.17 - Geht es um die Dokumentation von Applikationen, sollten Administratoren mit Entwicklern zusammenarbeiten. Neben der Bereitstellung und Verwaltung spielen schließlich auch viele Bereiche aus der Entwicklung eine große Rolle. lesen

„View“-basierte Softwarearchitektur-Dokumentation

„View“-basierte Softwarearchitektur-Dokumentation

27.03.19 - Eine Softwarearchitektur sinnvoll zu dokumentieren bedeutet, die relevanten Informationen des Systems so zu erfassen, dass diese jederzeit wieder abgerufen werden können. Was aber sind relevante Informationen, und wie halte ich sie so fest, dass Aufwand und Nutzen in sinnvollem Verhältnis stehen? lesen

Standardprozesse in der Software- und Systementwicklung

Standardprozesse in der Software- und Systementwicklung

22.10.19 - Manchmal sind Entwickler so in gewohnten Methoden festgefahren, dass sie nicht merken, wie langsam es vorangeht. Dabei können neue Prozesse frischen Wind in die Systementwicklung bringen. lesen

Dieser Beitrag stammt von unserem Partner-Portal Dev-Insider.de.

Kommentar zu diesem Artikel abgeben

Schreiben Sie uns hier Ihre Meinung ...
(nicht registrierter User)

Zur Wahrung unserer Interessen speichern wir zusätzlich zu den o.g. Informationen die IP-Adresse. Dies dient ausschließlich dem Zweck, dass Sie als Urheber des Kommentars identifiziert werden können. Rechtliche Grundlage ist die Wahrung berechtigter Interessen gem. Art 6 Abs 1 lit. f) DSGVO.
Kommentar abschicken
copyright

Dieser Beitrag ist urheberrechtlich geschützt. Sie wollen ihn für Ihre Zwecke verwenden? Kontaktieren Sie uns über: support.vogel.de/ (ID: 46220433 / Betrieb & Wartung)