Die Rolle der technischen Dokumentation in Software-Projekten

Wer jemals als „Normalsterblicher“ versucht hat, ein Handbuch zu einer Software zu lesen, wird in den meisten Fällen vor eine fast unlösbare Aufgabe gestellt. Viele Handbücher wimmeln geradezu vor unverständlichen Fachausdrücken und Schachtelsätzen. Das hilft dem Nutzer ganz und gar nicht, die Funktionen und Eigenschaften zu verstehen. Doch das ist nicht der einzige Grund, warum die technische Dokumentation bei einem Software-Projekt so wichtig ist.  

 

Übrigens: Technische Redakteure können sehr viel mehr als Bedienungsanleitungen zu verfassen. Sie kümmern sich beispielsweise um die technische Dokumentation bei der CE-Konformitätserklärung oder standardisieren und modularisieren Texte.  Eine weitere, nicht unerhebliche Rolle, spielt die technische Redaktion auch bei der Dokumentation von Software-Projekten.  

Was ist eigentlich eine Softwaredokumentation? 

 

Ganz simpel erklärt, handelt es sich bei dieser Art von Dokumentation um die Aufzeichnung von digitalen Prozessen. Diese wiederum enthalten Informationen für Entwickler und Benutzer (besagtes Handbuch).  
Und da wird es dann schon kompliziert. Denn eine Softwaredokumentation ist in der Regel in verschiedene Teilbereiche aufgesplittet. Diese sind:

  • Programmierung (Wie wurde das Programm entwickelt?) 
  • Benutzerdokumentation (Wie wird die Software bedient?) 
  • Datendokumentation (Wie funktioniert das Programm, und zwar mit allem drum und dran?) 

 

Diese Dokumentationen variieren wiederum in ihren Zielgruppen, und in der Form der Dokumentation. Denn einen Programmierer, der versucht, einen Fehler in einer Software in der Live Performance auszumerzen (Datendokumentation), interessieren ganz andere Dinge, als einen User, der wissen möchte, was sein Programm alles kann (Benutzerdokumentation). 
Die Programmier-Dokumentation enthält zudem auch noch die Quellcodes. Also die in Programmiersprache geschriebenen Programmanweisungen.  

 

Außerdem unterscheiden sich auch noch die einzelnen Dokumentationen. Es gibt die Systemdokumentation und die Projektdokumentation.  
Bei der Projektdokumentation beschreiben die Entwickler beispielsweise wie und womit eine Software programmiert wurde. Die Projektdokumentation begleitet die Software praktisch von der „Geburtsstunde“ bis zur Fertigstellung.  

Darum ist die Dokumentation von Softwareprojekten so wichtig 

 

Vielleicht denkt sich jetzt der eine oder andere: „Wieso soll ich denn mein Softwareprojekt dokumentieren lassen? Ich lass lieber nur eine Systemdokumentation für einen Endnutzer erstellen und gut ist.“ Ganz so einfach ist es leider nicht. Lediglich bei kleineren Programmen mit kurzer Lebensdauer kann man sich unter Umständen eine Dokumentation sparen. Natürlich ist eine Softwaredokumentation für den Endnutzer extrem wichtig, das steht außer Frage.  
Umfangreichere Software sollte immer dokumentiert werden, schon aus eigenem Interesse – mehr dazu später.  Zunächst einmal dient eine Software-Dokumentation dazu, Informationen zu transferieren. Entweder intern im Unternehmen oder nach außen.  

Was macht jetzt der Technische Redakteur in der Dokumentation von Softwareprojekten? 

 

In mancher Softwareentwicklung sieht es ähnlich wie in Maschinenbauunternehmen aus. Die Dokumentation zählt dort eher zu den, vorsichtig ausgedrückt, ungeliebten Aufgaben. Häufig wird der „Schwarze Peter Softwaredokumentation“ zwischen den einzelnen Personen und Abteilungen hin und her geschoben, bis es entweder vergessen wird oder der Praktikant übernimmt. Ein weiteres Argument, das auch sehr gerne herangezogen wird, um das Thema Dokumentation zu umgehen: „Wir arbeiten doch jetzt agil, da brauchen wir nichts mehr zu dokumentieren.“  

 

Das kann durchaus gutgehen. Problematisch wird es dann, wenn es zu Problemen im Live-Betrieb oder nach dem Rollout kommt, und alle erst mal ganz angestrengt überlegen müssen, wer wann für was zuständig war oder plötzlich der Kunde oder – noch schlimmer – der Gesetzgeber nach einer Dokumentation verlangt.  
Dann ist guter Rat oft teuer, und meistens mit vielen Überstunden verbunden. Zudem können solche „Dokumentationssprints“ sehr fehleranfällig sein. Denn gerade bei komplexen Prozessen kann es durchaus sein, dass kleine Details vergessen werden – mit fatalen Folgen.  
Außerdem ist es nicht immer gewährleistet, dass die komplette alte „Mannschaft“ dann noch greifbar ist – denn auch in der Softwareentwicklung gibt es eine Personalfluktuation. Beispielsweise werden Menschen krank oder sind nur befristet eingesetzt.  

 

Es hat also für ein Unternehmen durchaus Vorteile von Anfang an, einen technischen Redakteur in den Entwicklungsprozess mit einzubeziehen. Dieser kann auch gegebenenfalls die Leitung über das Projekt „Softwaredokumentation“ übernehmen. Übrigens: Auch Wartungsteams, die ja in der Regel nichts mit der Entwicklung zu tun haben, freuen sich sehr über eine nachvollziehbare (!) Dokumentation.  

 

Der weitere Vorteil: Viele technische Redakteure, die im Bereich Softwaredokumentation tätig sind, besitzen zumindest Grundkenntnisse im Bereich Programmierung. Deswegen können sie sich entsprechend schnell in das jeweilige Thema einarbeiten.  

 

In der Regel werden übrigens folgende Dokumente benötigt: 

  • Betriebshandbuch 
  • Benutzerhandbuch 
  • Schnittstellenspezifikationen 
  • Architekturdokument 
  • Testfallspezifikationen 
  • Release Notes 

 

Eines haben übrigens alle Dokumentationen gemeinsam: Sie sollten immer benutzerfreundlich und zielgruppengerecht geschrieben sein. Davon versteht ein technischer Redakteur grundsätzlich eine ganze Menge. Eine gute Benutzerdokumentation zeichnet sich vor allem dadurch aus, dass ein Nutzer schnell, und vor allem verständlich, die Information findet, die ihn dazu befähigt, die Software komplett zu nutzen.  
Kurz: Eine Information sollte immer schnell und ohne Umwege gefunden werden. 

 

Ein Programmierer steckt häufig viel zu tief in der Materie. Dadurch kann es für einen Entwickler durchaus schwierig werden, einem Außenstehenden etwas so zu erklären, dass dieser es auch versteht. „Sein“ Programm aus Nutzersicht zu betrachten ist für so manchen Entwickler leider ein Ding der Unmöglichkeit. Für einen technischen Redakteur ist das aber gerade das „tägliche Brot.“  

 

Die Projektdokumentation beziehungsweise eine Schnittstellendokumentation kann allerdings durchaus von einem Entwickler übernommen werden. Denn hier geht es in der Regel nicht um schön formatierte verständliche Texte sondern eher um „nackte“ Zahlen, Daten und Fakten.  

 

Wenn Sie Unterstützung bei der Dokumentation Ihrer Softwareprojekte benötigen, dann zögern Sie nicht Kontakt mit uns aufzunehmen.