Verständnis für die Prozesse einer Anwendung schaffen 11 Baustellen der Software-Dokumentation

Anbieter zum Thema

PresseBox - unn | UNITED NEWS NETWORK GmbH

FIS Informationssysteme und Consulting GmbH

Gute Software ist der Grundbaustein für den Erfolg – aber Nutzer müssen sie auch verstehen können. Ein kleines Framework für interne Richtlinien, direkt aus der Praxis.

Dokumentation von Software findet zum einen auf Quellcode-Ebene statt – das ungeliebte Spielfeld von Entwicklern selbst, gerne auch automatisiert. Zum anderen wird auf Produkt-Ebene dokumentiert, um die es hier auch gehen soll – also das gute alte Handbuch, das Manual, die Bedienungsanleitung.

Das Internet birst nur so vor lauter Artikeln mit Ratschlägen und Best Practices rund um die Entwicklung von Software, von etablierten Workflows über ein stabiles Tooling bis hin zu Aspekten der Zusammenarbeit, internen Standards und so weiter. Beim Thema Dokumentation sieht es da schon nicht ganz so umtriebig aus.

Aber auch hier ist planvolles Herangehen angesagt. Ein ordentliches Nutzerhandbuch ist erfolgskritisch und die Dokumentation als Projekt durchaus komplex. Im Folgenden geben wir allen Interessierten sozusagen ein kleines Framework an die Hand – Aspekte, die ein Dokumentationsteam klären sollte.

Dabei geht es nicht um Best Practices, sondern um die Sensibilisierung für aufkommende Probleme und Herausforderungen. Die Reihenfolge ist im Grunde recht beliebig; dennoch beginnt es mit Punkten aus der Planung und geht dann flüssig über zu den vielen „Kleinigkeiten“, die dann im Arbeitsalltag eine Rolle spielen.

Zielgruppe

Man könnte hier trivial „Nutzer der Software“ sagen, aber das ist freilich wenig hilfreich und auch nicht (unbedingt) korrekt! Beispielsweise könnten auch potenzielle Nutzer einen Blick in die Dokumentation werfen, wenn sie noch auf der Suche nach der passenden Software sind. Auch Journalisten und Hobby-Blogger könnten sich einbeziehen lassen: Präsenz in den Medien ist wichtig für den Erfolg und wenn der Einstieg zu schwierig ist, wird die Wahl meist auf ein anderes Produkt fallen.

Doch selbst wenn wirklich nur die eigentlichen Nutzer im Handbuch adressiert werden und alle anderen auf Marketing-Materialien, Blogs, Foren oder dergleichen verwiesen werden, ist die Definition der Zielgruppe wichtig: Was kann vorausgesetzt und was muss erklärt werden? Man kann Einsteiger mit zu viel Fachjargon genauso vergrämen wie versierte Nutzer mit Selbstverständlichkeiten und Redundanz!

Scope

Auch das klingt beinahe selbstverständlich: Was genau soll die Dokumentation leisten, was abdecken? Sollen lediglich einzelne Features von A bis Z beschrieben werden? Oder soll es Anleitungen für bestimmte Aufgaben geben? Vielleicht Empfehlungen und Best Practices? Soll das Handbuch eher eine Referenz sein oder Leser an die Hand nehmen und ähnlich einem Fachbuch durch die Software führen?

Es lohnt sich, genau festzulegen, was Leser vom Handbuch erwarten dürfen und was nicht. Alles andere führt später im Arbeitsalltag garantiert zu den immer gleichen Diskussionen und kostet Zeit.

Redaktionelle Standards

In aller Regel werden neue Autoren von Verlagen mit einem Regelwerk versorgt, gerne unter Namen wie „Style Guide“ oder „Redaktionsleitfaden“. Darin stehen Konventionen für den Aufbau von Artikeln, für Formulierungen (etwa „Du“ oder „Sie“), Formatierungen (zum Beispiel Listenformate), Gestaltung von Bildelementen und so weiter.

Analog dazu sollten auch im Rahmen einer Dokumentation sprachliche und stilistische Vorgaben gemacht werden – tendenziell sogar noch deutlich striktere als im journalistischen Umfeld. Schließlich erwarten Leser konsistente Handbücher, keine persönlichen, vom Autor geprägten Essays.

Nebenbei: Das ist nicht zu verwechseln mit einem drögen, unpersönlichen Schreibstil. Vermutlich über 90 Prozent aller Software-Handbücher lesen sich so, als hätte das Abziehbild eines Klischee-Bürokraten sie geschrieben – dabei spricht absolut nichts dagegen, lebendig und abwechslungsreich zu schreiben! Didaktisch ist das garantiert die bessere Variante.

Tooling

Die technischen Rahmenbedingungen bestimmen den Arbeitsalltag maßgeblich, auch beim Schreiben von Nicht-Code. Es beginnt mit der Wahl einer Auszeichnungssprache: Den supereinfachen Branchenprimus Markdown? Das deutlich mächtigere und effizientere Asciidoc? Oder doch gleich ein CMS, das von derlei Überlegungen befreit? Und wie gestaltet sich die Zusammenarbeit der Autoren?

Git etwa ist durchaus eine gute Wahl und vermutlich schon im Unternehmen verankert – doch sind Autoren keine Entwickler und in der Regel nicht mit Entwickler-Tools wie Git vertraut. Für das Schreiben an sich, Workflows wie „Review“, die Zusammenarbeit mit anderen Abteilungen, Übersetzungen und so weiter sollten Tools genauso sorgsam ausgewählt werden wie für die Entwicklung. Auch für den nächsten Unterpunkt ist diese Planung essenziell.

Ausgabeformate

Quellcode zu produzieren ist eine Sache, daraus fertige Produkte für unterschiedliche Plattformen zu bauen eine ganz andere. Und das gilt auch für Handbücher: HTML, ASCII-Text, PDF oder eBook-Formate? Vermutlich benötigen Sie mehrere Formate und das Tooling entscheidet darüber, wie kompliziert oder einfach die spätere Veröffentlichung sein wird.

Ein vielleicht nicht immer selbstverständlicher Aspekt: Lassen sich auch Teile von Handbüchern veröffentlichen? Vielleicht hätte ein Kunde gerne einen bestimmten Part der Dokumentation als eBook, um ihn zum Beispiel in Schulungen oder Umgebungen ohne Internetzugang zu verwenden.

Workflows

Schon Team-intern gibt es in der Dokumentation viel zu berücksichtigen: In welchen Einzelschritten werden Beiträge für das Handbuch erstellt? Von der Aufgabenerfassung und -verteilung über diverse Reviews und Korrekturen bis hin zu Übersetzungen und Veröffentlichungen müssen Schritte ineinandergreifen.

Hier gilt es – wie überall im Arbeitsleben – ganz konkrete Workflows zu definieren, auf Handlungs- wie auch auf technischer Ebene. Selbst wenn die Komplexität anfangs bei einer kleineren Software nicht gegeben scheint – sie wird sich irgendwann ergeben und nachträglich ist der Aufwand immens. Ein besonders wichtiger Workflow: Übersetzungen.

Übersetzungen

Ein amerikanisches Unternehmen mag es sich leisten können, lediglich in der eigenen Sprache zu dokumentieren – hierzulande ist neben Deutsch mindestens Englisch erforderlich, will man den Absatzmarkt nicht künstlich minimieren. Aber wie und wann wird übersetzt? Automatisch per KI? Per KI aber mit manuellem Review? Über eine Übersetzungsplattform mit Hilfe der Community? Mit professionellen Übersetzern?

Zwei Zeitpunkte wollen hier verwaltet werden: Zum einen wann übersetzt und zum anderen wann veröffentlicht wird. Und was passiert bei Aktualisierungen? Werden diese erst publiziert, wenn alle Sprachversionen aktuell sind? Oder noch nicht aktualisierte Versionen gekennzeichnet? Und wie überhaupt übergeben Autoren Aktualisierungen an die Übersetzung?

Man könnte an dieser Stelle etliche weitere Fragen aufwerfen, aber es läuft eigentlich nur auf Folgendes hinaus: Übersetzungsprozesse sehen auf den ersten Blick simpel aus, bringen im Alltag aber jede Menge zu berücksichtigender Kleinigkeiten mit sich!

Kommunikation: Entwickler

Das vielleicht größte inhaltliche Problem beim Schreiben von Handbüchern: Tendenziell ist man der erste Mensch, der darüber schreibt – bei Fragen lohnt sich eine Google-Suche daher meist nicht. Klar, die Infos müssen von den Entwicklern kommen. Also müssen Kommunikationskanäle bestehen, Ansprechpartner für bestimmte Features genannt werden, Entwickler angewiesen sein, ihre spärliche Zeit bisweilen auch dem Dokumentationsteam zur Verfügung zu stellen und so weiter.

Entwickler sind auch essenziell für die Planung, wann was geschrieben wird: Welche Features sind fertig entwickelt? Wann werden welche Features in welcher Softwareversion veröffentlicht? Derlei Dinge müssen im Vorfeld geklärt werden, wenn das Handbuch auch wirklich auf dem aktuellen Stand sein soll.

Kommunikation: Support

Der vielleicht selbstverständlichste Punkt unseres kleinen Frameworks: Beim Support laufen viele Fragen und Probleme auf, die viel zu spezifisch für ein Handbuch sind – oder gerne auch mal auf den Teilbereich vor der Tastatur zurückzuführen sind. Aber generell hat der Support ein gutes Gespür für die Anliegen und Fragen der Kundschaft. Das gilt nicht nur für den klassischen Support im Ticket-Geschäft, sondern auch für jegliche Art von Consulting.

Kommunikation: Management

Genauso wichtig ist der Kanal zum Produktmanagement, denn letztlich wird dort entschieden, welche Features entwickelt, welche Versionen veröffentlicht und wie sie vermarktet werden. Wenn auf dem jährlichen Nutzertreffen Features angekündigt werden, die dann bei Veröffentlichung nicht dokumentiert sind, ist Ärger gewiss.

Und auch die sonstigen Management-Bereiche sollten – gegebenenfalls über den Vermittler Produktmanagement – verzahnt werden. So müssen Ziele mit der Unternehmensleitung koordiniert werden, es bieten sich Kooperationen mit dem Marketing an, das schließlich teils mit ähnlichem Content arbeitet (Blogs, Präsentationen etc.).

Kommunikation: Community

Leser werden Fragen stellen, Leser werden Ansprüche anmelden – bei kostenloser wie -pflichtiger Software. Aber sie werden auch helfen! Plant man die Community ein, kann sie wirklich hilfreich sein, sei es, um Fehler und blinde Flecken zu entdecken, Fragen in Foren zu beantworten und Best Practices zu erläutern, die zu speziell fürs Handbuch sind, oder auch Übersetzungen auf Übersetzungsplattformen beizusteuern.

Plant man die Community hingegen nicht ein, wird sie entweder zeitfressend in den Arbeitsalltag eingreifen oder schlicht öffentlich ihren Frust ablassen. Beides sollte dringendst vermieden werden.

Zum Abschluss noch ein wenig Sensibilisierung für Ausmaße: Stellen Sie sich vor, ein Windows-Entwickler würde den Explorer-Dialog „Start“ in zum Beispiel „Allgemein“ abändern – im Quellcode vielleicht nur ein einzelner Eintrag in einer Sprachdatei.

Für die Dokumentation könnte dies schnell Tausende neuer Screenshots und Textanpassungen bedeuten. Ähnliche Anpassungsaufwände fallen schon an, wenn „nur“ das Standard-Theme einer Software geändert wird – weshalb es nie schadet, ein paar personelle Ressourcen für Fleißarbeit in der Hinterhand zu haben.

(ID:48647914)