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.

Anforderung Erklärung
Hilfreich Ein Dokument muss einen Nutzen stiften. Wenn das Dokument für niemanden hilfreich ist, so wird es nicht benötigt.
Korrekt Fehlerhafte 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.
Aktuell Dokumentation 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 benutzen Es 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ändlich Fakten, 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 änderbar Je einfacher Dokumente änderbar sind, desto wahrscheinlicher ist es, dass Dokumente wirklich angepasst und gepflegt werden.
Kurz Weniger 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.
Versioniert Ein 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.
Verantwortet Jedes Dokument hat einen Besitzer, der das Dokument verantwortet und der für die Pflege verantwortlich ist.
Top-Down organisiert Es 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ärend Tatsachen 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 Redundanz Es 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ön Wenn Dokumente, dann aber bitte auch schön formatiert und ohne Rechtschreibfehler. Das bisschen mehr Aufwand sollte uns die Dokumentation dann schon wert sein.
Eindeutig Begriffe 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:

Isolationsdiagramme in der Medizintechnik

Bei der Zulassung nach IEC EN 60601-1 wird der TÜV in der Regel ein Isolationsdiagramm verlangen.  Sucht man in der Grundnorm 60601-1 nach dem Wort Isolationsdiagramm, so wird man nicht…

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.