Software Dokumentation Referenz

Dokumentationsübersicht

30% des Aufwandes eines Softwareprojektes sollte in die Dokumentation fliessen. So weit, so gut. Aber von welchen Arten von Dokumentation gehen solche Schätzungen überhaupt aus? Mit anderen Worten: Wie wird 'anständig' dokumentiert?

Bevor wir uns die eigentlichen Dokumentationsarten näher anschauen, lassen Sie uns kurz vor Augen führen, mit welchen Mitteln dokumentiert werden kann:

Handbuch	Genaue Beschreibung eines Sachverhaltes unter der Annahme, daß der Leser diese Dokumentation am Stück von vorne bis hinten durchliest.
Referenz	Tabellenartige Auflistung von Fakten, wobei die Gestaltung so optimiert sein sollte, daß schnell Informationen wiedergefunden werden, wenn nur ein Name oder ein Synonym bekannt sind - Gute Referenzen enthalten Querverweise bei ähnlichen oder sich beeinflussenden Sachverhalten
Diagramme	Visuelle Darstellung zur Übersicht.

Insbesondere der Unterschied zwischen dem Referenz- und dem Handbuchstilmittel ist recht entscheidend. Meistens wird mit "Dokumentation" nämlich der Handbuchstil assoziiert und das führt nicht selten zu haarsträubenden und ineffektiven Dokumentationen. Ein Blick auf die Dokumentationen, die aus einem Softwareprojekt heraus entstehen können, verrät, daß die "Referenz" häufig das geeignetere Mittel zum Zweck ist:

Übersicht über die möglichen Dokumentationen eines Softwareprojektes.
Idee	Planung	Entwicklung	Produktivschaltung	Fortlaufend
Funktionale Spezifikation	Technische Spezifikation	Quellcode-Dokumentation Installationsanleitung Konfigurationsreferenz Datenschema Komponentenreferenz Zugriffsreferenz Release Notes	Standard Test Script Content Owner Konfigurations-Referenz Prozessdokumentation Benutzerhandbuch Trainingsunterlagen	Problemliste

Die Übersicht erhebt nicht den Anspruch auf Vollständigkeit. Zugleich werden wohl nicht für jedes Softwareprojekt alle gelisteten Dokumentationen erforderlich sein. Mit ihrer Zuordnung zu den Phasen eines Softwareprojektes soll die Übersicht einfach eine Basis für Entscheidungen bieten, wie im spezifischen Einzelfall dokumentiert wird. Im folgendenen werden die einzelnen Dokumentationsarten näher erläutert.

Funktionale Spezifikation (Functional Specification)

Die Funktionale Spezifikation beschreibt das Verhalten und Aussehen von Funktionaliät in einem Softwareprodukt und wird normalerweise vom Auftraggeber/Kunden oder in enger Zusammenarbeit mit Auftraggeber/Kunden eines Softwareprojektes erstellt. Die Funktionale und die Technische Spezifikation können als zwei Seiten eines Vertrages angesehen werden. In einem guten Softwareprojekt beschreiben beide Dokumentationen unterschiedlliche Aspekte der gleichen Sache.

Eine Funktionale Spezifikation macht Sinn für Erweiterungen, d.h. Neue Funktionalität, oder Verbesserungen bestehender Funktionalität, nicht aber für Fehlerbeschreibungen. Die Funktionale Spezifikation wird aussagekräftig, wenn folgende Mittel verwendet werden:

Wireframes
- Simulation von Screenshots
- je genauer desto aussagekräftiger
- 'unwichtiger' Kontext wird einfach als Rechteck vereinfacht
- einfach in Powerpoints erzeugt
Use Cases
- Beschreibung, welche Funktionen in welchen Situationen benutzt werden.
- Sowohl die Funktionen als auch die dazugehörigen Situationen werden beschrieben.
- je genauer beschrieben soll, was passiert, wenn eine Funktion genutzt wird, desto besser
- auch Angaben, was nicht passieren sind hilfreich
Personas
- beispielhafte Darstellung, welche Rolle die Software wofür nutzen würde

Beispiel-Wireframe für ein Login-Formular:

Technische Spezifikation (Technical Specification)

Die Technische Spezifikation beschreibt die Datenstrukturen und Programmkonzepte eines Softwareproduktes und wird normalerweise vom technischen Partner oder dem Entwickler eines Softwareprojektes erstellt. Die Funktionale und die Technische Spezifikation können als zwei Seiten eines Vertrages angesehen werden. In einem guten Softwareprojekt beschreiben beide Dokumentationen unterschiedlliche Aspekte der gleichen Sache.

Die Technische Spezifikation wird aussagekräftig, wenn folgende Mittel verwendet werden:

Datenflußdiagramme
Programmablaufpläne oder Struktogramme - für's Grobe und nicht so detailliert wie die Programmierung
Prozeßbeschreibung

Admin Guide

Der Admin sollte die zentrale Anlaufstelle für Systemadministratoren sein, sobald Fragen auftauchen. Er stellt eine Möglichkeit für den Entwickler dar, dem Administrator alle betriebsrelevanten Informationen zur Verfügung zu stellen. Das Hauptaugenmerk liegt auf Fakten und nicht auf rethorisch ausgeklügelten Satzkonstruktionen.

Der Admin Guide enthält im Idealfall folgende Bestandteile:

Quellcode Dokumentation (Source Code Documentation)
Welchen Basiskonzepten und -methoden folgt die Kodierung und warum? Welche Auswirkungen ergeben sich daraus?
Beispiele:
- Die Daten xy werden auf z gecacht. Grund: Performance; Auswirkungen: 30 Minuten Wartezeit, bevor Änderungen aktiv werden
- Fehlerbehandlung der Eingabezeile abc erfolgt clientseitig per Javascript; Grund: flüssiger Eingabeablauf; Auswirkung: Abhängigkeit vom Internet Explorer
Installationsanleitung (Install Guide)
Welche Schritte müssen in welcher Reihenfolge abgearbeitet werden? Ein durchschnittlicher Support-Mensch sollte die Installation mithilfe der Installationsanleitung durchführen können.
Konfigurationsreferenz für Admin (Configuration Setting Reference for Admin)
Die Konfigurationsreferenz für Admin sollte für jede mögliche Konfigurationseinstellung (egal, ob im Admin-Bereich, in Konfigurations-Dateien oder -Datenbanken änderbar) folgende Kriterien dokumentieren:
- Name
- Wo kann sie geändert werden
- Default Wert, falls vorhanden
- Minimum-Wert, falls vorhanden
- Maximum-Wert, falls vorhanden
- ausgeschlossene Werte, falls vorhanden
- Auswirkung, was passiert, wenn diese Einstellung geändert wird + worst case + best case
- Grund, warum wurde diese Einstellung eingeführt
Beispiel:
Name:cachesize (in MB), Position:abc-Pfad/xyz.ini - Sektion [Cache], Default: 20, Min:1, Max:2000;Auswirkung: Je höher, desto besser ist die Performance und desto schlechter ist die Nutzbarkeit. Cachetime=1 führte unter Testbedingungen zu Lesezugriffen von 1 Minute. Der Performance-Zuwachs war mit größeren cachesizes als 20 minimal. Grund: Feature Request
Datenschema (Data Schema)
Das Datenschema macht Sinn für alle Systeme, in denen Daten gespeichert und referenziert werden, hauptsächlich bei Datenbanken. Das Datenschema sollte eine grafische Übersicht der Beziehungen der Datencontainer (in Datenbanken Tabellen) und eine Referenz der Eigenschaften (in Datenbank Spalten) beinhalten.

Bespiel:
Für eine Datenbank mit den Tabellen users, cars und carsproducers bestehen folgende Beziehungen: ...mit folgender Referenz: Tabelle USERS Name Typ Default Beschreibung userid Int 0 Eindeutige Identifizierung username VarChar(200) NULL Benutzername Tabelle CARPRODUCERS Name Typ Default Beschreibung producerid Int 0 Eindeutige Identifizierung companyname VarChar(200) NULL Herstellername Tabelle CARS Name Typ Default Beschreibung carname VarChar(200) NULL Modellname _userid Int 0 Zeiger auf users.userid _producerid Int 0 Zeiger auf carproducers._producerid
Komponentenreferenz (Component Reference)
Dir Komponentenreferenz listet die Bestandteile des Projektes (z.B.Datei a,b,c..) und die vorausgesetzten Systemkomponenten (z.B. Tomcat,.Net,System xyz Indexing). Mit der Komponentenreferenz hilft, Installationsfehler aufzudecken.
Zugriffsreferenz (Access Reference)
Die Zugriffsreferenz enthält die Zugriffdaten zu den Systemkomponenten, die zugriffgeschützt sind. Sie sollte jeweils folgende Information enthalten:
- Benutzername
- Passwort
- Verbindungsdetails (z.B.URL, IP, Programm)
Das Speichern oder Aufschreiben von Verbindungsdetails kann sicherheitsrelevant sein. Es sollte daher immer abgewogen werden, ob die Zugriffsreferenz elektronisch, handgeschrieben oder mündlich übertragen wird. In den meisten Fällen macht es Sinn, die Zugriffsreferenz separat vom Admin Guide aufzubewahren. Die Zuordnung zum Admin Guide in dieser Dokumentation folgt der Idee, daß an dieser Stelle alle vom Entwickler bereitgestellten Information aufgeführt werden und ist nicht bindend!

Release Notes

Release Notes werden immer dann fällig, wenn neue Appplikationsversionen der Zielgruppe zur Verfügung gestellt werden. Damit vermittelt der Entwickler dem Auftraggeber/Kunden, welche Änderungen zwischen zwei Versionen stattgefunden haben. Sinnvollerweise enthalten die Release Notes eine Liste der Erweiterungen und der Fehlerbehebungen.

Standard Test Script

Das Standard Test Script erlaubt es, die Hauptfunktionalitäten einer Software zu testen. Vom Applikationseigentümer erstellt enthält es typischerweis detailierte Anweisungen in der Form Klicke A, Gebe xyz ein, sodaß auch Menschen, die die Software normalerweise nicht benutzen würden, den Test ausführen können. Solche Tests sollten immer bei Versionswechseln durchgeführt werden, um sicherzustellen, daß 'nichts kaputtentwickelt' wurde. Das Erstellen des Test Scriptes erfordert etwas Kreativität, damit möglichst eine vielfältige Bandbreite von Funktionen mit möglichst wenig Aktionen getestet wird.

Beispielhafter Auszug aus einen Standard Test Script: Schritt/ID Aktion Erwartete Reaktion ... 21 Klicke den blauen nach oben zeigenden Pfeil des letzten Eintrages Der Eintrag rutscht eine Stelle höher 22 Klicke das Stift-Icon des Eintrags Das Bearbeitungsfenster öffnet sich ...

Content Owner Konfigurations-Referenz (Content Owner Configuration Reference)

Die vom Entwickler oder Applikationseigentümer erstellte Content Owner Konfigurations-Referenz zielt darauf ab, "Superuser" zu unterstützen, in Systemen in denen solche besonderen Benutzer erweiterte Funktionalitäten anwenden dürfen, z.B. Änderungen von Rechten der "normalen Benutzer" oder wenigstens deren Eingaben. Ein schönes Anwendungsbeispiel sind Blog-Autoren, die auch konfigurieren dürfen, wie ihr Blog aussieht. Natürlich wäre es schön, wenn sie wüßten, warum und wie was konfigurieren.

Für jede mögliche Konfigurationseinstellung sollten folgende Kriterien dokumentiert werden:

Name
Wo kann sie geändert werden
Default Wert, falls vorhanden
Minimum-Wert, falls vorhanden
Maximum-Wert, falls vorhanden
ausgeschlossene Werte, falls vorhanden
Auswirkung, was passiert, wenn diese Einstellung geändert wird + worst case + best case
Grund, warum wurde diese Einstellung existiert

Beispiel:
Name:newsdays (in days), Einstellungen/ Anzeige, Default: 7, Min:0, Max:100;Auswirkung: Alle Objekte, die in den letzten newsdays Tagen angelegt worden sind, werden mit einem Lämpchen Icon besonders hervorgehoben. Grund: Es werden unterschiedliche News Perioden kommuniziert.

Prozessdokumentation (Processes Documentation)

In der Prozessdokumentation beschreibt der Applikationseigentümer für den Kunden und für die Administratoren, wie Softwarefunktionalitäten eingerichtet, geändert und deaktiviert werden können, die sich nicht selbstverständlich aus der Softwarehandhabung heraus ergeben. Immer wenn irgendetwas beantragt werden muß, damit etwas im Zusammenhang mit der Software passiert, ist das ein Fall für die Prozessdokumentation. Wenn dagegen beispielsweise nur ein Schalter in der Software geklickt werden muß, damit etwas passiert, ist das wohl eher nichts für die Prozessdokumentation - es sei denn, neben dem Klick sind noch eine Reihe weitere Aktionen erforderlich, um etwas zu erreichen.

Benutzerhandbuch (User Guide)

Das Benutzerhandbuch erstellt der Applikationseigentümer für seine Kunden. In der Regel sollte das Handbuch einfach geschrieben sein und zwar so, daß die Kapitel logisch aufeinander aufbauen, es also fortlaufend gelesen werden kann. Es ist wichtig, eine ausgewogene Balance aus Detailtreue und Fokussierung auf das Wesentliche zu finden. Kein Mensch liest dicke Schinken, die vom Hölzchen auf's Klötzchen kommen und auf der anderen Seite kann man sich das Handbuch sparen, wenn nur an der Oberfläche 'rumbeschrieben' wird.

Trainingsunterlagen (Training Material)

Trainingsunterlagen unterstützen Training. Ohne Training keine Trainingsunterlagen. Idealerweise werden sie vom Trainer in seinem Stil erstellt. Sinnvoll sind eine Handvoll Stichpunktlisten pro Trainingshalbtag als Gedankenstütze.

Problemliste (Issue List)

In der Problemliste sammelt der Applikationseigentümer alle Verbesserungsvorschläge, Fehlerbeschreibungen oder Erweiterungsideen für die Einarbeitung in neue Versionen oder als Grundlage für Entscheidungen über das weitere Vorgehen. Tatsächlich trifft "Issue List" den Kern der Sache eher Problemliste. In der Praxis hat es sich als praktisch erwiesen, für jedes Issue folgende Daten gespeichert werden:

Schritt/ID
Name/Kurzbeschreibung
Gemeldet/Beantragt von
Gemeldet/Beantragt in Version
Gemeldet/Beantragt Datum
Priorität (hoch,mittel,niedrig)
Klasse (Verbesserung,Fehler,Neue Funktion)
Status (Idee,Planung,Entwicklung,Aktiv,Abgelehnt)
Implementiert in Version
Aufwandsschätzung Entwicklung

Haben Sie Fragen zur Dokumentations-Referenz? Klicken Sie hier für Hilfe.