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.
|
|
| Dipl.-Ing. Goran Madzar, Gesellschafter, Senior Systems Engineer E-Mail: madzar@medtech-ingenieur.de Tel.: +49 9131 691 240 |
|
Benötigen Sie Unterstützung bei der Entwicklung Ihres Medizingeräts? Wir helfen gerne! Die MEDtech Ingenieur GmbH bietet Hardware-Entwicklung, Software-Entwicklung, Systems Engineering, Mechanik-Entwicklung und Beratung aus einer Hand. Nehmen Sie Kontakt mit uns auf. |
|
<td“>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.
| 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 | |
| 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, sodass 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