In einem Software-Projekt passiert eine ganze Menge. Projektmitarbeiter produzieren das Software-Produkt, also Code in einer oder mehreren Programmiersprachen und Konfigurationen für den Betrieb. Abhängig von der Projektorganisation und dem gewählten Vorgehen – phasen-orientiert, iterativ oder agil – schreiben Manager, Analysten und Spezialisten verschiedener technischer Disziplinen im Laufe der Zeit eine ganze Reihe von Dokumenten.

01 Was ist eine Produktdokumentation

Definition

Dokumente können wir ganz grob in Projekt- oder Produktdokumentation einteilen. Zur Produktdokumentation zählen folgende Unterlagen:

  1. Betriebshandbuch
  2. Benutzerhandbuch
  3. Systembeschreibung
  4. Architekturdefinition
  5. Glossar

Benutzer- und Betriebshandbuch sind für viele Projekt ganz klar vorgeschrieben durch Vorgaben und Richtlinien im Unternehmen (abgeleitet aus Normen ITIL bzw. CMMI). Ohne die beiden Handbücher gibt es schon rein formal keine Einführung der Software für den produktiven Einsatz.

Ein Glossar ist eine alphabetisch sortierte Sammlung von Fachbegriffen aus dem Geschäftsfeld im Unternehmen, in dem die Software zum Einsatz kommt. Das Glossar ist das “Wörterbuch” des Projektes. Es ist ein Mini-Lexikon, zugeschnitten auf das Produkt.

Alle anderen Arten von Unterlagen zählen zur Projektdokumentation. Die wichtigsten Vertreter sind ganz allgemein alle Arten von Anforderungen, Lastenhefte, Pflichtenhefte, ein Backlog, das Projekthandbuch, Vereinbarungen oder Verträge.

ktip Vorgaben sind in großen Unternehmen häufig in Form einer umfassenden Dokumentenrichtlinie festgeschrieben.

In vielen Projekten legt der Auftraggeber fest, dass jedes Produktinkrement in einer vom Unternehmen festgelegten Form zu liefern ist – inklusive vorgeschriebener Dokumentation. Die Sprache für die Projekt- und Produktdokumentation wird durch Auftraggeber und Projektorganisation bestimmt.

Sprache

Bei der Sprache müssen wir zwischen Projekt- und Produktdokumentation sowie Code und Konfiguration unterscheiden. Die Projektsprache ist ein entscheidendes Kriterium für die Effizienz der Kommunikation in der Projektorganisation und für die Qualität der Dokumentation.

Projektdokumentation sollte in einer Sprache verfasst werden, die jeder Projektmitarbeiter und die Stakeholder versteht. Ist das Unternehmen international tätig, wird häufig die englische Sprache gewählt, als kleinster gemeinsamer Nenner. Für einzelne Projektmitarbeiter kann das allerdings zur Belastung werden.

Eine Produktdokumentation sollte immer in der Sprache der fachlichen Domäne geschrieben sein. Ist die Domänensprache nicht Englisch, führt eine Übersetzung ins Englische nicht nur zu zusätzlichen Aufwänden, sondern in der Kommunikation auch häufiger zu Missverständnissen. Mitarbeiter haben nicht immer den notwendigen Wortschatz in Englisch, um ihr Wissen vollständig und fehlerfrei in einer für sie fremden Sprache zu erfassen.

Bei Code und Konfigurationen wird die englische Sprache bevorzugt. Allein schon wegen der Programmiersprachen wirkt eine andere Sprache als Englisch fast schon fremd. Auch die vielfach im Einsatz befindliche Middleware und Frameworks tragen zu diesem Trend bei. Trotzdem ist es empfehlenswert, die Begriffe der fachlichen Domäne zu erhalten. Im Fall einer Domänesprache, die nicht Englisch ist, kann es für die Kommunikation zwischen Stakeholder und Product-Owner auf der einen Seite und dem cross-funktionalen Team auf der anderen Seite sehr nützlich sein, wenn alle gemeinsam die gleichen Originalbegriffe verwenden. Es ist ein sehr einfacher Weg, eine gemeinsame Sprache zu etablieren.

Systembeschreibung

In der Systembeschreibung geht es konkret um den Versuch, das fachliche Produktwissen vollständig und widerspruchsfrei zu erfassen. Sie besteht aus der lückenlosen Dokumentation des Problemraumes, in dem sich die Nutzer des Systems bewegen, also aller Anwendungsfälle, Sonderfälle und Fehlerfälle der Funktionalität des Systems.

Zur Systembeschreibung zählen auch “Verständnismodelle”, die wichtige Informationsobjekte und Nachrichten aus fachlicher Sicht erklären. Fachklassenmodelle und bei nachrichten-orientierten Systemen Nachrichtenmodelle bilden gemeinsam mit dem Glossar die Grundlage für die gemeinsame Sprache im Projekt.

Ein Product-Owner will mit der Systembeschreibung einen vollständigen und möglichst aktuellen Überblick über den fachlichen Umfang der Software erlangen mit dem Ziel, Verhandlungen mit den Fachbereichen über die Zuführung finanzieller Mittel für das Projekt erfolgreich zu gestalten.

Architekturdefinition

Die Architekturdefinition ist der Versuch, den durch die Systembeschreibung definierten Problemraum zu verstehen und durch Entscheidungen und Einschränkungen den Lösungsraum für das Produkt zu beschreiben. Qualitätsmerkmale der Software und nicht-funktionale Aspekte sind solche Einschränkungen. Wichtige weitere Einschränkungen ergeben sich aus Vorgaben und Richtlinien für Software-Projekte.

Die Architekturdefinition ist der Sammelbegriff für technischer Aspekte der Produktdokumentation. Sie besteht aus dem Architekturentwurf und der Beschreibung der Systemstruktur. Der Code des Produktinkrementes spielt hier eine wesentliche Rolle bei der exakten Spezifikation von Schnittstellen und Datenstrukturen. Zur Vermeidung von redundanten Beschreibungen werden Konfigurationen, Skripte, Schemadefinitionen und andere Beschreibungssprachen der Entwickler als gültige Dokumente betrachtet und in den Bausteinen im Wiki nur referenziert.

Die Systemstruktur umfasst außerdem einen Überblick über den Entwurf, die grundlegende Gestaltung und das Verhalten der Elemente der Benutzeroberflächen der für Nutzer des Systems sichtbaren Apps, Web- oder Desktop-Anwendungen. Diese Beschreibungen dürfen jedoch nicht mit einem Benutzerhandbuch verwechselt werden.

Eine weitere wichtige Quelle für Vorgaben und Einschränkungen ist die Betriebsorganisation. Der Betrieb einer Software ist mit Kosten verbunden. Lösungen, die sich auf Betriebskosten auswirken, sind für den Erfolg eines Projektes sehr wichtig. Hier kommt es immer wieder zu Diskussionen, weil eine Betriebsorganisation typischerweise Innovationen ablehnt, während Innovationen für Entwickler notwendig sind, um Ziele wie Skalierbarkeit, Robustheit, Wartbarkeit und Sicherheit zu erfüllen.

ktip Die Fabel “The chicken and the pig” wird in diesem Zusammenhang gerne zitiert. Mit den Entwicklern als “pig”, weil sie von faulen Kompromissen und zweitbesten Lösungen direkt betroffen sind.

Die Architekturdefinition wird von Entwicklern für Entwickler erstellt. Umfang und Detaillierung wird daher maßgeblich von den Bedürfnissen der Entwickler bestimmt.

Fazit

Ein einigermaßen komplexes Software-Produkt ohne Handbücher ist für mich nicht vorstellbar. Jedoch können oder müssen wir uns über den Umfang der Handbücher Gedanken machen. Die Systembeschreibung und die Architekturdefinition sind beide in manchen Fällen Vertragsgegenstand! Beide Unterlagen müssen dann vom Projekt erstellt und laufend aktualisiert werden. Wenn wir also akzeptieren, dass ein gewisses Maß an Dokumentation aus verschiedenen Gründen notwendig ist, dann sollten wir es ganz im agilen Gedankengut zu unserem Vorteil nutzen.