Dokumentation: Hilfreich statt frustrierend

© Jelena – stock.adobe.com

„Dokumentation ist oft frustrierend.“ Diese Aussage resoniert vermutlich bei vielen. Es wird viel Zeit in Dokumentation gesteckt, die letztendlich niemand liest. Dabei muss das gar nicht so sein! Dieser Blogartikel gibt einen Überblick über typische Probleme bei der Dokumentation und Tipps, wie diese Probleme gelöst werden können.

Unklare Zielgruppe und fehlender Zweck

Eine Ursache vieler Probleme besteht darin, dass Zweck und Zielgruppe der Dokumentation nicht ausreichend geklärt sind. Das führt meist dazu, dass die Zielgruppe das Dokument nicht versteht. Es muss also klar sein: Für wen wird das Dokument geschrieben? Geht es um IT‑Entwickler, Anwender oder Management? Ein Entwickler erwartet technische Details, während das Management an einem Überblick und aussagekräftigen Zahlen interessiert ist. Auch wenn die Zielgruppe klar ist, soll noch der Zweck des Dokuments festgelegt werden. Beispielsweise steht fest, dass ein Dokument an IT‑Entwickler gerichtet ist. Aber geht es in dem Dokument eher um Schnittstellenbeschreibungen oder um eine detaillierte Kontrollbeschreibung einer Anwendung? Sind Zweck und Zielgruppe eines Dokuments aber bereits klar, ist die Lösung zu vielen anderen Probleme fast schon intuitiv.

Fehlender Überblick

Wie oft habe ich mich seitenlang in Dokumente eingearbeitet und letztendlich trotzdem nicht gewusst, was der Autor mir sagen möchte und worum es geht? Eine gute Einleitung hätte hier geholfen. In der Einleitung muss stehen, an wen das Dokument gerichtet ist (Zielgruppe) und worum es geht (Zweck). Außerdem hilft ein inhaltlicher Überblick ganz am Anfang, sich als Leser schnell zurechtzufinden und gezielt in Details einzutauchen. Beispielsweise ist ein Systemkontext ein guter fachlicher Überblick über eine Anwendung, da hier bereits relevante Nutzer, Umsysteme und Anwendungsfälle des Systems genannt werden. Mehr zum Systemkontext gibt es übrigens auch bei uns im Blog.

Abbildung 1: Inhaltlicher Überblick mit dem Systemkontext am Beispiel eines Online-Shops (Quelle: CampusLab GmbH)

Zu lange Dokumente

Wer liest sich gerne durch hunderte Seiten Text? Weniger ist mehr! Es soll nur das aufgeschrieben werden, was tatsächlich relevant ist. Passt eine Information zu Zweck und Zielgruppe des Dokuments? Kann ich den beschriebenen Sachverhalt nur mit der Information richtig verstehen? Wenn nicht, dann kann sie in der Regel weggelassen werden.

  • Möchten Sie sich Techniken zur Dokumentation aneignen? Das geht am besten mit unserem E-Learning Requirements Engineering! Probieren Sie den Kurs doch mit der kostenlosen Preview-Funktion einfach aus.

Nur Text/nur Abbildungen

Viel alleinstehender Text ist selten verständlich. Oft würden Abbildungen und Modelle dem Leser helfen, den Sachverhalt viel schneller zu verstehen und Missverständnisse zu vermeiden. Umgekehrt gilt aber auch – viele Abbildungen ohne begleitenden Text sind ebenso unverständlich. Die gesunde Mischung macht’s! Abbildungen sollen aber zielgerichtet gewählt werden, denn sonst ist die…

Art der Darstellung unpassend

Insbesondere bei Abbildungen und Modellen ist die Zielgruppe wieder wichtig. Denn die Zielgruppe soll diese auch verstehen! Das Management ist vermutlich nicht am Klassendiagramm einer Anwendung interessiert, das zu viele Details in einer unbekannten Notation liefert und eher von IT‑Entwicklern verstanden wird.

Es gibt noch weitere Gründe, wegen denen Dokumentation scheitert und Lösungen, wie es besser geht. Unklarer Zweck und Zielgruppe sind aber erfahrungsgemäß der Punkt, an dem es oft hakt und der ungelöst viele weitere Probleme verursacht. Wer aber die oben genannten Punkte berücksichtigt, der hat auch schon einen großen Schritt in Richtung hilfreiche und verständliche Dokumentation gemacht.

Scroll to Top