So erstellen Sie eine moderne Dokumentation für Anwendungen

Zu großen, komplexen Applikationen existiert oft eine unübersichtliche Dokumentation, die schlecht zu lesen ist und in der Suchende nichts finden. Wir skizzieren ein Konzept für eine schlanke und zukunftsbeständige Dokumentation für Applikationen. [...]

Seit Applikationen geschrieben und betrieben werden, gibt es Dokumentationen: Projektdokumentationen für die Entwicklung und Betriebsdokumentationen für den laufenden Betrieb von Applikationen. Ihre Erstellung ist eine ungeliebte Tätigkeit, die gerne aufgeschoben wird oder manchmal auch ganz entfällt, weil das Budget schon aufgebraucht ist. Dabei weiß jeder von uns, wie wichtig Dokumentation ist – zum Beispiel wenn Anwendungen von einem Dienstleister an einen anderen übergeben werden oder wenn neue Mitarbeiter sich einarbeiten wollen.

Dokumentationen insbesondere von großen, gewachsenen, geschäftskritischen Systemen sind oft in einem beklagenswerten Zustand. Sie aktuell zu halten, nimmt unserer Erfahrung nach durchschnittlich fünf bis zehn Prozent des Gesamtaufwands von Entwicklungsprojekten in Anspruch. Die meisten Betriebsverantwortlichen von geschäftskritischen Applikationen werden – befragt nach der Qualität der Dokumentation – antworten: „nicht ausreichend“. Wenn also die Dokumentation schlecht, aber wichtig und vor allem teuer ist, wie lässt sie sich dann verbessern? Unternehmen können am WAS und am WIE ansetzen.

Zum WAS

Zu einer Anwendung gehören immer zwei Arten der Dokumentation: die dauerhafte Dokumentation, die die gesamte Anwendung im aktuellen Zustand abbildet, und die temporäre oder Projektdokumentation, die eine Änderung beschreibt.

Die dauerhafte Dokumentation ist eine statische Referenz zur Anwendung. Ziel der temporären Dokumentation ist die Unterstützung des kreativen und kollaborativen Prozesses der Entwicklung. Aus diesen unterschiedlichen Zielen wird schon deutlich, dass die eine Dokumentation nicht gleichzeitig den Zweck der anderen erfüllen kann.

Die dauerhafte Dokumentation wird beispielsweise für folgende Aufgaben eingesetzt:

• Geschäftsprozess, den die Anwendung unterstützt,
• Funktionen / fachliche Entitäten,
• Anforderungen in regulierten Umgebungen,
• Kontextdiagramm / Komponentendiagramm,
• technische Architektur,
• Regressionstests,
• Betriebshandbuch,
• Benutzerhandbuch.

Temporäre Dokumentationen kommen zum Einsatz, wenn es um folgende Aufgaben geht:

• Anforderungen / User Stories,
• Lastenhefte / Pflichtenheft,
• Design / technische Feinspezifikation,
• Datenbankmodell,
• Klassendiagramm,
• Testfälle, Testdokumentation.
• Release Notes.

Microsoft: Visuelle Einführung in die Azure-Grundlagen

Zum WIE

Um den aktuellen Stand der Applikation zu dokumentieren, existieren zwei Ansätze. Zum einen kann die dauerhafte Dokumentation die Sammlung der temporären Dokumente sein. Das spart Zeit in der Erstellung, ist aber auf Dauer unlesbar: Wenn der Leser wissen will, warum eine Funktion ist, wie sie ist, muss er die gesamte Dokumentation rückwärts lesen, bis er das Dokument findet, in dem der Einbau dieser Funktion beschrieben ist.

In der anderen Variante wird die dauerhafte Dokumentation nach Abschluss jeder Änderung aktualisiert. Dazu werden nur dauerhaft relevante Informationen aus der temporären Dokumentation übernommen. Das ist aufwendig, aber besser lesbar.

Für das WIE ist auch wichtig, wie die Dokumentation abgelegt wird. Das geschieht meistens in Form verschiedener Dokumente (zum Beispiel in Word) auf einer gemeinsamen Plattform wie etwa SharePoint. So kommt eine große Zahl Dokumente zusammen, die kollaborativ gut zu bearbeiten ist, aber die Dokumente sind schlecht zu durchsuchen, untereinander nicht verlinkt und ihre Version ist gegebenenfalls nicht aktuell.

Diese Aspekte sind aber für eine moderne und zukunftsfähige Dokumentation besonders wichtig. Es geht um gute Durchsuchbarkeit, Verlinkung (zum Beispiel zwischen Testfällen und Anforderungen und zwischen Diagrammen und Prosatexten, die diese beschreiben) sowie um Versionssicherheit. Auch liegt es im Interesse der Entwickler, insgesamt wenig zu dokumentieren, sich auf das Wesentliche zu beschränken und mit wenigen Dokumenten auszukommen. Wie lässt sich das erreichen?

Aus unserer Sicht sind die wesentlichen Elemente einer guten, dauerhaften Dokumentation:

• Eine knappe Beschreibung der Anwendungsfunktionen: Was leistet das System? WelchenGeschäftsprozess unterstützt es? Welche Funktionen bietet es? Diese Beschreibung der fachlichen Anforderungen kann rein textuell sein. Zusätzlich ist ein fachliches Entitätendiagramm empfehlenswert, auch ein Kontextdiagramm ist hilfreich.
• Ebenfalls wichtig ist die Liste der Anforderungen, die zu den vorhandenen Funktionen gehören. Mit ihr lässt sich nachvollziehen, warum eine bestimmte Funktion gebraucht wird.
• Auch eine aufs Wesentliche beschränkte Beschreibung der technischen Architektur ist unentbehrlich: Wie ist das System aufgebaut? Hier sind vor allem Diagramme dienlich: Kontextdiagramme, Komponentendiagramme und Abbildungen der technischen Architektur.
• Und schließlich braucht es Regressionstestfälle als Instrument, um sicher Änderungen an der Applikation vornehmen zu können. Dabei durchlaufen alle Änderungen vor ihrer Integration in die Anwendung ein festgelegtes Set an Regressionstestfällen, das alle wesentlichen Funktionen des Systems abdeckt. Jeder Regressionstestfall muss auf eine oder mehrere Anforderungen verweisen, deren Erfüllung er prüft. So wird sichergestellt, dass eine Änderung, die alle Regressionstestfälle besteht, die Funktionalität der Anwendung nicht beschädigt.

Geht es um die temporäre Dokumentation, so sollte diese den Anforderungen der Entwicklung genügen und auf eine leichte Integration in die dauerhafte Dokumentation ausgelegt sein. Unbedingt erforderlich sind hier:

• eine Beschreibung der neuen und veränderten Anforderungen in der gleichen Form und Nomenklatur (zum Beispiel Nummerierung) wie in der dauerhaften Dokumentation;
• Änderungen am fachlichen Entitäten-Diagramm: Es kann aus der dauerhaften Dokumentation verwendet werden und nur die Änderungen werden eingetragen und hervorgehoben;
• Änderungen am Kontextdiagramm;
• Änderungen an der technischen Architektur;
• gegebenenfalls weitere temporäre Dokumen­te, die für die Entwicklung benötigt werden, damit sie zum Beispiel offshore erfolgen kann (Datenbankmodelle, Klassendiagramme etc.);
• Testfälle (inklusive Regressionstestfälle), die auf Anforderungen verweisen.

Nach Abschluss des Entwicklungsprojekts kann aus den temporären Dokumenten leicht die dauerhafte Dokumentation angepasst werden. Dort werden die Dokumente dann aktualisiert und in neuer Version zur Verfügung gestellt.

Viele SOC-Mitarbeiter ignorieren Security-Alerts

Das neue WIE

Stellt sich noch die Frage nach einem moderneren WIE. Die Dokumentation kann weiterhin in Form von Word- und anderen Dokumenten erfolgen. Damit lässt sich zumindest manuell Versionssicherheit herstellen. Durchsuchbarkeit und Verlinkbarkeit sind damit aber weiterhin nicht gegeben, was die Verwendung der Dokumentation deutlich erschwert.

Deshalb empfiehlt es sich, die Möglichkeiten von Tools wie JIRA oder Confluence für die ­Dokumentation zu nutzen. Texte und Diagramme sind durchsuchbar, einzelne Elemente können verlinkt werden, etwa Testfälle oder Anforderungen. Wer beispielsweise die Auswirkungen eines Fehlers im Betrieb sucht, wird einfacher die zugehörige Anforderung finden und kann so die Auswirkungen des Fehlers besser abschätzen. Um hier Versionssicherheit herzustellen, ist es aber weiterhin notwendig, nach erfolgter Änderung einen Abzug des aktuellen Stands der Dokumentation abzulegen.

Sicher lohnt es sich nicht, umfangreiche bestehende Dokumentationen für große Systeme nun auf diese Art und Weise umzuarbeiten. Wer aber für neue Systeme mit einer sparsamen Dokumentation in diesem Sinne beginnt, wird sich viel Aufwand jetzt und in der Zukunft sparen.

*Dr. Ursula Löbbert-Passing: IT-Management-Beraterin bei der LEXTA Consultants Group. Sie verantwortet das Beratungsportfolio zum Thema Applikationen, unter anderem die Benchmarking-Methoden für Applikationsbetrieb und -entwicklung.

**Dr. Sebastian Löbbert: Project Director bei Capgemini. Seit 20 Jahren entwickelt er individuelle Softwarelösungen und verwendet dafür seit 2006 auch gerne Scrum.