Anforderungen an effektive Dokumentation

Bei dem Wort “Dokumentation” schrecken viele direkt zurück. Dokumentation erstellen, lesen oder etwas suchen – meist eine Angelegenheit, die nicht mit viel Freude verbunden ist. Dabei ist Dokumentation notwendig und wichtig. Das Ziel ist es, dass der Aufwand im Projekt mit Dokumentation kleiner ist als ohne. Wäre man ohne Dokumentation schneller, wozu würde man sich dann die Arbeit überhaupt machen? Die Dokumentation hat das Ziel, Entscheidungen festzuhalten und sichtbar zu machen. Damit ist Dokumentation ein Werkzeug, welches als Denkhilfe, Aufzeichnung und Diskussionsgrundlage dient. Damit Dokumentation effektiv ist, sind ein paar Anforderungen einzuhalten. Diese möchte ich in diesem Artikel vorstellen.

AnforderungErklärung
HilfreichEin Dokument muss einen Nutzen stiften. Wenn das Dokument für niemanden hilfreich ist, so wird es nicht benötigt.
KorrektFehlerhafte Informationen sind schlimmer als keine Informationen. Daher ist darauf zu achten, dass die Dokumentation korrekt ist. Fehler in Dokumenten führt dazu, dass das Vertrauen in die Dokumentation rapide abnimmt und damit sinkt der Wert der Dokumentation insgesamt. Daher ist Korrektheit oberstes Ziel.
AktuellDokumentation altert und damit kann es passieren, dass Dokumente nicht mehr aktuell sind. Was gestern korrekt war, kann heute bereits falsch sein. Daher ist es wichtig Dokumentation zu hegen und zu pflegen.
Einfach zu benutzenEs muss für den Konsumenten einfach sein, dass Dokument zu finden und zu benutzen. Feste Strukturen und Konventionen können dabei hilfreich sein.
Leicht verständlichFakten, Fakten, Fakten und an die Leser denken! Dieser Slogan trifft auch bei Dokumentation zu. Bei der Erstellung der Dokumentation muss man an den Leser denken. Welche Informationen benötigt er und welche Sprache versteht er? Wie kann ich als Ersteller dem Leser die Lektüre verständlich darbieten?
Leicht änderbarJe einfacher Dokumente änderbar sind, desto wahrscheinlicher ist es, dass Dokumente wirklich angepasst und gepflegt werden.
KurzWeniger ist mehr. Denn zu lange Dokumente liest niemand und damit verfehlen sie ihr Ziel. Es geht nicht darum Romane zu schreiben, sondern die wichtigen Informationen zu dokumentieren.
VersioniertEin Dokument muss eine Version haben. Damit können verschiedene Versionen des gleichen Dokumentes unterschieden werden. Idealerweise ist man in der Lage über eine Versionsverwaltung die verschiedenen Versionen zu verwalten.
VerantwortetJedes Dokument hat einen Besitzer, der das Dokument verantwortet und der für die Pflege verantwortlich ist.
Top-Down organisiertEs soll für den Leser möglich sein den Sachverhalt ausgehend von einem hohen Abstraktionsgrad mit wenigen Details, schrittweise bis zur Verfeinerung mit mehr Details zu lesen.
ErklärendTatsachen sind oft im Produkt nachvollziehbar. Interessant sind aber die Herleitung und Begründung von Entscheidungen. Die Frage, warum wurde etwas auf eine bestimmte Art und Weise realisiert, interessiert den Leser oft mehr, als das wie.
Frei von RedundanzEs sollte angestrebt werden, Informationen nur an einem Ort zu dokumentieren. Redundanz führt zu der Gefahr von Widersprüchen und ist für die Pflege von Dokumentation ungeeignet. Nur wenn die Information an dieser Stelle für das Verständnis des Lesers notwendig ist, dann können Informationen auch redundant verwendet werden.
SchönWenn Dokumente, dann aber bitte auch schön formatiert und ohne Rechtschreibfehler. Das bisschen mehr Aufwand sollte uns die Dokumentation dann schon wert sein.
EindeutigBegriffe und Darstellungen sollen eindeutig verwendet werden. Ein Glossar soll die Begriffe definieren. Darstellungen und Diagramme sind zu erläutern, falls sie Interpretationsspielraum bieten.

Schaffen Sie eine positive Haltung zur Dokumentation, so dass diese nicht als lästige Arbeit, sondern als integraler Bestandteil des Schaffens gilt. Nehmen Sie die Dokumentation immer in die “Definition of Done” eines Arbeitspaketes mit auf. Und machen Sie sich bewusst, dass Sie für den Leser und nicht den Autor dokumentieren.

Viele Grüße,

Goran Madzar

Auch interessant:

Entropie in der Entwicklung bekämpfen

Manchmal verschwinden Dinge spurlos - einfach weg. Trösten kann man sich dann mit Aussagen wie "ein bisschen Schwund ist immer!". Dieses Verschwinden von Dingen treibt auch in Entwicklungsprojekten sein Unwesen.…

Goran Madzar

Seit Mai 2007 bin ich zusammen mit meinem Kollegen Martin Bosch selbständig. Wir haben ein Ingenieurbüro im Innovations- und Gründerzentrum in Erlangen aufgebaut. Hier entwickeln wir für Kunden in der Medizintechnik mit unseren Mitarbeitern Lösungen für die Produkte von Morgen.

Getagged mit: , ,

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.