Ein Softwareprojekt nachvollziehbar dokumentieren und bewerten

Das Projekt ist fertig, aber die Geschichte dahinter fehlt

Die Elbauen Fahrradservice GmbH verwaltet Reparaturaufträge bisher in einer Tabellenkalkulation. Ein kleines Entwicklungsteam hat deshalb das Webportal “Werkstattblick” gebaut. Beschäftigte erfassen darin Fahrräder, ordnen Reparaturschritte zu und informieren Kundinnen und Kunden über den aktuellen Status.

Am Ende des Projekts liegen Quellcode, Testprotokolle und mehrere Besprechungsnotizen vor. Was fehlt, ist der Zusammenhang. Warum wurde eine Warteschlange für Benachrichtigungen gewählt? Welche Anforderung belegt der Lasttest? Weshalb dauerte die Umsetzung eines Arbeitspakets länger als geplant? Eine Person außerhalb des Teams könnte diese Fragen mit den vorhandenen Dateien nicht zuverlässig beantworten.

Genau dafür ist eine Projektdokumentation da. Sie ist keine nachträglich ausgeschmückte Tätigkeitsliste. Sie macht den Weg vom betrieblichen Problem bis zum bewerteten Ergebnis nachvollziehbar. Leserinnen und Leser sollen erkennen können, welche Entscheidungen du auf welcher Grundlage getroffen hast und wodurch du das Ergebnis belegst.

In dieser Lektion baust du diese Nachweiskette für “Werkstattblick” auf. Du brauchst dafür Grundwissen über Anforderungen und Softwaretests. Projektplanung und Vorgehensmodelle werden hier nicht neu erklärt. Dafür gibt es die eigene Lektion zu Projektmanagement-Grundlagen.

Eine Dokumentation verbindet Behauptungen mit Belegen

Eine schwache Dokumentation berichtet nur: “Danach wurde die Datenbank umgesetzt und anschließend getestet.” Der Satz nennt Tätigkeiten, aber weder Grund noch Ergebnis.

Eine tragfähige Fassung verbindet vier Fragen:

1. Was war gefordert? Die Anforderung oder das Ziel gibt den Maßstab vor.
2. Was wurde entschieden und umgesetzt? Die Dokumentation erklärt Auswahl und Handlung.
3. Was kam dabei heraus? Ein beobachtbares Ergebnis ersetzt die bloße Erfolgsmeldung.
4. Wodurch ist das belegt? Testfall, Messung, Protokoll oder anderes Projektergebnis macht die Aussage prüfbar.

Für “Werkstattblick” sieht ein kurzer Ausschnitt so aus:

Die Tabelle ist noch keine vollständige Projektdokumentation. Sie zeigt aber ihr Rückgrat: Jede wichtige Aussage hat einen Bezug nach hinten und einen Nachweis nach vorn. Diese Rückverfolgbarkeit hilft auch nach dem Projekt, wenn jemand eine Entscheidung verstehen oder einen Fehler eingrenzen will.

Die Gliederung folgt der beruflichen Handlung

Die Fachinformatikerausbildungsverordnung verlangt für den Prüfungsbereich “Planen und Umsetzen eines Softwareprojektes”, dass Planung und Durchführung anforderungsgerecht dokumentiert werden. Sie schreibt damit keine überall identische Kapitelvorlage vor. Auch konkrete Formvorgaben können von der zuständigen Stelle und dem jeweiligen Verfahren abhängen.

Für die inhaltliche Führung trägt folgende Reihenfolge:

Diese Reihenfolge ist ein Inhaltsmodell, keine allgemeingültige Seitenstruktur. Wenn deine zuständige Stelle verbindliche Vorgaben für Einreichung, Umfang oder Anhänge nennt, gelten diese Vorgaben für dein Verfahren. Die Nachweiskette bleibt trotzdem nützlich, weil sie den fachlichen Zusammenhang trägt.

Ausgangslage und Ziel setzen den Maßstab

Die Ausgangslage beschreibt nicht die gesamte Unternehmensgeschichte. Sie zeigt den Zustand, der das Projekt auslöst. Bei “Werkstattblick” reichen dafür wenige konkrete Punkte:

• Reparaturdaten stehen in einer gemeinsam genutzten Tabellenkalkulation.
• Mehrere Beschäftigte überschreiben gelegentlich gleichzeitig Einträge.
• Statusanfragen werden telefonisch beantwortet und unterbrechen die Werkstattarbeit.
• Die Auftragsnummer ist bereits im vorhandenen Kassensystem verfügbar.

Aus dieser Lage entsteht ein Projektziel. Es beschreibt den gewünschten Zustand, ohne die technische Lösung vorwegzunehmen:

Die Werkstatt soll Reparaturaufträge zentral bearbeiten und den aktuellen Bearbeitungsstand über eine auftragsbezogene Abfrage bereitstellen können. Die Lösung soll vor der Übergabe anhand vereinbarter Funktions-, Rechte- und Leistungskriterien geprüft werden.

Anforderungen machen dieses Ziel überprüfbar. “Das Portal ist benutzerfreundlich” wäre zu offen. “Eine Beschäftigte kann einen neuen Auftrag mit Fahrrad, Kontaktweg und erstem Status ohne zusätzliche Anleitung erfassen” beschreibt eine beobachtbare Handlung.

Entscheidungen brauchen Kriterien statt Rückschau

Eine Dokumentation soll nicht so tun, als sei jede Entscheidung von Anfang an offensichtlich gewesen. Sie zeigt echte Alternativen und den Maßstab der Auswahl.

Für die Statusbenachrichtigung prüft das Team drei Varianten:

Weil die Benachrichtigung zeitnah erfolgen und ein Mailfehler die Statuspflege nicht blockieren soll, entscheidet sich das Team für die Warteschlange. Die Begründung ist stärker als “Variante zwei ist moderner”. Sie verbindet Auswahlkriterien mit der betrieblichen Situation.

Ein knapper Entscheidungsnachweis enthält deshalb:

• den Anlass und die betroffene Anforderung,
• die ernsthaft betrachteten Varianten,
• die vorab passenden Kriterien,
• die Entscheidung samt fachlicher Begründung,
• erkennbare Folgen oder neue Risiken.

Die Entscheidung selbst gehört in den Haupttext, wenn sie für Zielerreichung oder Vorgehen wesentlich ist. Vollständige Bewertungsunterlagen können je nach Vorgabe in einen Anhang passen. Der Haupttext darf sich aber nicht auf einen unkommentierten Anhang verlassen.

Umsetzung erklären, ohne ein Arbeitstagebuch zu schreiben

Ein Arbeitstagebuch zählt jeden Handgriff in zeitlicher Reihenfolge auf. Eine Projektdokumentation wählt die Schritte aus, die für Anforderungen, Entscheidungen und Ergebnis relevant sind.

Für die Warteschlange sind vier Umsetzungsschritte erklärungswürdig:

1. Die Statusänderung wird zusammen mit einem Benachrichtigungsauftrag gespeichert.
2. Ein Hintergrunddienst übernimmt offene Aufträge.
3. Nach erfolgreichem Versand markiert er den Auftrag als erledigt.
4. Bei einem vorübergehenden Fehler bleibt der Auftrag mit Fehlerhinweis für einen erneuten Versuch erhalten.

Details wie das Anlegen jedes Ordners oder jede umbenannte Variable tragen diese Erklärung nicht. Ein kurzer Ausschnitt aus Konfiguration oder Code ist nur sinnvoll, wenn du daran eine Entscheidung, eine Sicherheitsmaßnahme oder einen besonderen Lösungsweg erklärst. Quellcode ersetzt die Erklärung nicht.

Tests schließen die Nachweiskette

Ein Testkapitel ist keine Liste grüner Häkchen. Es zeigt, ob die Anforderungen unter definierten Bedingungen erfüllt wurden. Dazu braucht jeder wesentliche Test einen Bezug zur Anforderung, einen Ausgangszustand, die Handlung, das erwartete Ergebnis und das tatsächliche Ergebnis.

Eine Testfall-ID schafft noch keinen Beleg. Entscheidend sind überprüfbare Bedingungen und Ergebnisse. Wenn ein Test fehlschlägt, ist das kein Grund, ihn aus der Dokumentation zu entfernen. Gerade dann wird sichtbar, wie du die Ursache eingegrenzt, die Lösung angepasst und erneut geprüft hast.

Abweichungen zeigen professionelle Steuerung

Im Projektplan waren sechs Stunden für die Benachrichtigungsfunktion vorgesehen. Beim Test zeigte sich, dass der zuerst gewählte Mailversand im Webaufruf bei verzögerter Antwort auch die Statusänderung verzögerte. Das Team stellte deshalb auf die Warteschlange um. Die Funktion benötigte tatsächlich zehn Stunden.

Eine sachliche Abweichungsanalyse beantwortet vier Fragen:

• Was wich ab? Der Aufwand lag vier Stunden über dem Plan; die technische Lösung änderte sich.
• Warum? Der frühe Leistungstest zeigte eine Kopplung zwischen Statusänderung und externem Maildienst.
• Wie wurde entschieden? Das Team priorisierte das vereinbarte Antwortverhalten und setzte die Warteschlange um.
• Welche Wirkung hatte das? Ein optionaler Komfortfilter wurde nach Abstimmung nicht umgesetzt. Die vereinbarten Kernanforderungen und der Übergabetermin blieben erhalten.

Der Abschnitt sucht keine schuldige Person. Er zeigt, dass ein neuer Befund erkannt, bewertet und gesteuert wurde. Auch eine gute Planung kann von der Realität abweichen. Problematisch wird eine Abweichung erst dann für die Nachvollziehbarkeit, wenn sie verschwiegen oder nur mit “unerwarteten Schwierigkeiten” erklärt wird.

Ergebnis und Reflexion beantworten verschiedene Fragen

Die Ergebnisbewertung prüft das Produkt gegen die Projektziele. Für “Werkstattblick” werden die vereinbarten Funktions-, Rechte- und Leistungstests bestanden. Der optionale Komfortfilter fehlt, gehörte nach der Abstimmung aber nicht mehr zum zugesagten Lieferumfang. Das Ergebnis ist damit nicht “zu 100 Prozent perfekt”, sondern anhand des gültigen Solls eingeordnet.

Eine wirtschaftliche Einordnung vergleicht ebenfalls Plan und Ist. Dazu gehören beispielsweise der geplante und tatsächliche interne Aufwand sowie erkennbare laufende Aufwände für Betrieb oder Wartung. Eine reine Behauptung wie “Das Projekt war wirtschaftlich” reicht nicht. Welche Kennzahlen tragen, hängt vom Auftrag und den im Betrieb verfügbaren Daten ab.

Die Reflexion bewertet dagegen das Vorgehen. Für das Team war der frühe Leistungstest hilfreich, weil er die problematische Kopplung vor der Übergabe sichtbar machte. Weniger gut war, dass die Auswirkung eines langsamen Maildienstes nicht schon beim Variantenvergleich als eigenes Kriterium festgehalten wurde. Für ein Folgeprojekt soll die Abhängigkeit von externen Diensten deshalb bereits in der technischen Bewertung geprüft werden.

Eine Reflexion ist dann nützlich, wenn sie aus einer Beobachtung eine konkrete Folgerung ableitet:

Beobachtung: Die betrieblichen Testdaten kamen später als geplant. Wirkung: Der Exporttest konnte erst am Ende des Testzeitraums vollständig ausgeführt werden. Folgerung: Datenformat, Umfang und Bereitstellungstermin werden im nächsten Projekt als eigenes Arbeitsergebnis mit verantwortlicher Rolle vereinbart.

“Die Zusammenarbeit war gut” ist dagegen zu allgemein. Der Satz zeigt weder, woran die Bewertung festgemacht wird, noch was das Team daraus lernt.

Übergabe und offene Punkte machen das Ergebnis nutzbar

Die Dokumentation endet nicht bei “Projekt erfolgreich abgeschlossen”. Für die Übergabe hält das Team fest:

• welche Version und welche Bestandteile übergeben wurden,
• welche Betriebs- und Nutzungsdokumentation dazugehört,
• welche Tests mit welchem Ergebnis abgeschlossen sind,
• welche bekannten Einschränkungen oder offenen Aufgaben bestehen,
• wer für Betrieb, Support und Folgeentscheidungen zuständig ist,
• welche Einweisung durchgeführt wurde und welche Rückmeldungen daraus entstanden.

Die eigene Projektdokumentation, technische Betriebsunterlagen und eine Anleitung für Nutzerinnen und Nutzer haben unterschiedliche Zielgruppen. Sie dürfen aufeinander verweisen, ersetzen sich aber nicht. Eine Projektentscheidung wird nicht dadurch nachvollziehbar, dass irgendwo eine Bedienungsanleitung existiert.

Prüfe Entscheidungen statt Fachwörter

Formuliere selbst eine belastbare Abweichungsanalyse

Was du aus der Lektion mitnimmst

Eine gute Projektdokumentation macht nicht möglichst viele Tätigkeiten sichtbar. Sie macht die fachlich wichtigen Zusammenhänge nachvollziehbar:

• Die Ausgangslage erklärt, weshalb das Projekt gebraucht wird.
• Ziele und Anforderungen liefern den Maßstab.
• Varianten und Kriterien tragen die Entscheidung.
• Die Umsetzung zeigt die relevanten Schritte und Folgen.
• Tests verbinden Anforderungen mit beobachtbaren Ergebnissen.
• Abweichungen erklären Ursache, Reaktion und Planwirkung.
• Ergebnisbewertung und Reflexion trennen Produkt und Vorgehen.
• Übergabe und offene Punkte sorgen dafür, dass andere weiterarbeiten können.

Damit steht das Grundgerüst. Konkrete Formvorgaben für deine Einreichung prüfst du zusätzlich bei der für dein Verfahren zuständigen Stelle. Diese Lektion vermittelt bewusst keine regionale Vorlage und ersetzt weder die Projektmanagement-Grundlagen noch eine Einführung in klassische oder agile Vorgehensmodelle.

Belegmatrix