Wir starten heute mit dem ersten Teil unserer Blog-Serie zum Thema “Software-Dokumentation”. Mein Name ist Oguzhan Cansever. Als Senior Projektmanager bei gjuce kenne ich mich durch das Management zahlreicher Kundenprojekte bestens mit der Thematik aus. Außerdem gebe ich mein Wissen als Lehrbeauftragter an der FH Köln für Lean Product Management weiter.
Auch in unseren Teams wird die Erstellung von Software-Dokumentationen manchmal als leidig oder unnötig empfunden. Wann und in welchem Umfang eine Dokumentation notwendig ist, und wie ihr es schafft, im Team eine Akzeptanz für Dokumentationen herzustellen, zeige ich euch in dieser Serie in vier einzelnen Blog-Artikeln. In den einzelnen Artikeln richten wir den Blick auf folgende Kernfragen:
- Welche Projektmanagement-Methode wird im Projekt eingesetzt?
- Geht es um die Dokumentation für ein Software-Projekt oder ein Software-Produkt?
- Welchen Einfluss haben Teamgröße und Skills auf die Dokumentation?
Viel Spaß beim Lesen!
Oggy
Teil 1: “Wie finde ich heraus, ob und welche Doku ich benötige?”
Welche Tätigkeit rund um die Software-Entwicklung ist in der Agenturwelt besonders unbeliebt? Ganz offensichtlich die Software-Doku! Das liegt nicht nur daran, dass die Umsetzungsgeschwindigkeit von Projekten immer höher und die Halbwertszeit von Software-Projekten immer kürzer wird. Auch die Tatsache, dass viele Projektbeteiligte eigentlich gar nicht genau wissen, in welchem Umfang sie welche Bereiche der Software überhaupt dokumentieren sollen, macht die Erstellung von Dokus häufig zu einem wirklich unbeliebten Thema im Projekt: Den Entwickler nervt es nur und hält es vom Coden ab, der zuständige Projektmanager will Projekt-Ergebnisse pünktlich abliefern - eine Doku passt da einfach nicht rein...
Es gibt zahlreiche Normen, Methoden, Arten, Einsatzgebiete, Zielgruppen, Meinungen, ISO IEC IEEE 26514, 26515, 15289, Std 830. Da blickt man nicht so einfach durch.
Um Ordnung zu schaffen und ein wiederverwendbares Schema für unterschiedliche Software-Projekte innerhalb eures Unternehmens zu gewinnen, solltet ihr einen Prozess etablieren, der extrem schlank ist, keine festen Dokumentations-Arten vorschreibt, den Projektzyklus mit hilfreichen Schlüsselfragen begleitet und eine Akzeptanz aller Projektbeteiligten erfährt.
Welche Arten von Software Dokumentationen gibt es?
Zunächst ist es ratsam eine sinnvolle Taxonomie auszuwählen, die die Einsatzgebiete der Dokumentation darstellt. Das folgende Modell bildet eine gute Basis, um sich einen ersten Überblick zu schaffen:1
- Prozessdokumentation:Dokumente zum Entwicklungsprozess – z.B. Richtlinien, Handlungsanweisungen, Standards und Musterdokumente
- Projektdokumentation:
Planung und Leitung des Entwicklungsprojekts – z.B. Projektauftrag, Projektplan, Projektstatusberichte, Projektabschlussbericht, Projektstakeholder
- Systemdokumentation:
Für die Konstruktion und Wartung benötigte Dokumente – z.B. Begriffslexikon, Anforderungsspezifikation, Spezifikation der System Testfälle, Abnahme Spezifikation, Systemarchitektur und Programmcode
- Qualitätsdokumentation:
Dokumente zur analytischen Qualitätssicherung – z.B. Audit-Protokolle, Test- und Review-Berichte, Abnahmebericht
Diese Art der Kategorisierung unterscheidet noch nicht zwischen traditionellen und agilen Vorgehensmodellen. Außerdem gibt sie noch keine konkreten Vorgaben, welche Art der Dokumentation zu erstellen ist, und welches Teammitglied für die Erstellung zuständig ist.
Acht Schlüsselfragen fürs Team
Am Anfang steht ja meist die Frage, ob ich in meinem Projekt überhaupt dokumentieren muss, und wenn ja, welche Bereiche und wie kontinuierlich dokumentiert werden sollen?
Im Folgenden sind acht Fragen mit erläuternden Beispielen aufgeführt. Ich empfehle euch, diese Fragen in Regelmeetings mit dem Team zu diskutieren. Die Antworten auf diese Fragen können je nach Projektphase und Teamstruktur stark variieren. Ihr solltet immer versuchen, im Team einen Konsens zu finden, der eine interdisziplinäre und phasenübergreifende Sichtweise ermöglicht.
1. Ist das zu dokumentierende Wissen nur in der aktuellen Phase relevant?
Beispiel: Ein Use-Case Diagramm aus der Konzeptionsphase, das zu einer schriftlichen Anforderungsbeschreibung führt, ist möglicherweise auch für die spätere Arbeit der Entwicklungsteams hilfreich. Häufig werden Use Case Diagramme bei der initialen Anforderungsanalyse erstellt und später durch User Stories ersetzt. Stattdessen können die Use Case Diagramme in die finalen User Stories inkludiert werden, um den Entwicklern in der Umsetzungsphase das Verständnis der Anforderung zu erleichtern.
Beispiel: Dokumentationen von dynamischen Artefakten wie Variablen sind möglicherweise nicht sinnvoll, da sich diese ständig ändern. In diesem Falle ist es ratsam, sich mit dem Entwicklungsteam auszutauschen, um einzuschätzen wie lange solche technischen Informationen gültig bleiben und wie detailliert sie dokumentiert werden sollten. Häufig verzichtet man hier auf eine Dokumentation oder kommentiert nur die betreffenden Stellen im Code. Klassen und Funktionen einer Software sollten dagegen im Code als Kommentar dokumentiert werden.
2. An welche Zielgruppe richtet sich die Dokumentation?
Es ist wichtig sich zu vergegenwärtigen, wer die potentiellen Leser der Doku sind. Der Komplexitätsgrad der Doku muss an deren fachliches Know-how angeglichen werden.
Beispiel: Ein Entwicklerteam besteht aus Entwicklern für das Frontend (FE) und das Backend (BE). BE-Entwickler stellen den FE-Entwicklern diverse Webservices zur Verfügung, die die Oberflächen einer Anwendung mit Daten und Funktionen versorgen. In diesem Fall besteht die Zielgruppe aus FE-Entwicklern, die Backend-Programmiersprachen in der Regel nicht beherrschen. FE-Entwickler benötigen eine Dokumentation, um die existierenden Webservices zu finden und zu verstehen. Die Dokumentation soll einerseits sehr übersichtlich sein und andererseits die Möglichkeit bieten, in die Tiefe einzelner Services einzusteigen, um zu verstehen, welche Datentypen und Methoden vorgesehen sind. Eine Dokumentation mittels Swagger (https://swagger.io/tools/swagger-ui/) ist dafür gut geeignet.
Beispiel: Ein Software-Unternehmen motiviert seine Mitarbeiter, kleine experimentelle Anwendungen umzusetzen, bei denen interessante Ansätze, Architekturen, Patterns, neue Technologien etc. ausprobiert werden können. Diese Anwendungen werden in einem internen Code-Repository gesammelt, und die daraus gesammelten Erfahrungen werden in internen Demos und Entwickler-Gesprächen an Kollegen weitergegeben. Ein solches Experiment-Projekt wird auf GitHub veröffentlicht und eine sehr knappe ReadMe-Datei als Dokumentation angeboten. Daraufhin kann es passieren, dass ihr mit Fragen und Kommentaren von Interessenten, die versuchen den Code zu verstehen, bombardiert werdet. Bei öffentlichen Software-Projekten solltet ihr also die Zielgruppe sehr gut einschätzen und versuchen, eine detaillierte Dokumentation anzubieten.
3. Lohnt sich eine Dokumentation auch bei kleinen (Teil-) Projekten?
Beispiel: Auch wenn es bereits eine Code-Dokumentation gibt, kann es zusätzlich sinnvoll sein, die Softwarearchitektur und das technische Konzept zu dokumentieren. Vor allem bei kleinen Projekten (max. Projektdauer 6 Monate), werden technische Entscheidungen und Konzepte häufig umgehend umgesetzt, ohne sie zu dokumentieren. So bleiben die Erfahrungen und das Wissen zu diesem Projekt allein in den Köpfen der Projektbeteiligten. Abhängig von Weiterbetrieb, Systemskalierung und späteren Wartungsarbeiten, sollte der Umfang der Dokumentation gemeinsam mit Team und Kunde entschieden werden.
Beispiel: Lean Startups gehen häufig mit sehr schlanken Software-Plattformen und beschränkten Funktionalitäten an den Start. Mit diesem Prototyp (MVP) kann eine Produktidee vertestet werden. Wird das Produkt am Markt ein Erfolg, wird der Prototyp (MVP) meist gelöscht und ein komplett neues und skalierbares System realisiert. In diesem Fall kann es sinnvoll sein, die Dokumentation nur auf Produktanforderungen und Code-Kommentare zu begrenzen.
4. Welche Art der Dokumentation ist adäquat und ausreichend?
Beispiel: Ein einfaches Storyboard oder ein Flow Chart ist vielleicht vollkommen ausreichend um ein Benutzerführungsszenario für das UI-Development zu beschreiben ohne die einzelne Schritte in Textform zu erfassen. Ob dies ausreicht, können nur Designer und Entwickler entscheiden. Diese Art der Dokumentation ist allerdings nicht ausreichend für die Business Stakeholder, die möglicherweise einzelne Touchpoints über verschiedene Kanäle analysieren möchten und eine Art Customer Journey Map benötigen.
Beispiel: Immer mehr Softwarearchitekten setzen auf geteilte Softwarearchitekturen und Microservices. Damit ist es leichter, modulare Änderungen vorzunehmen und zu deployen, da in Monolithen eventuell das gesamte System angepasst werden muss. Allerdings muss sichergestellt werden, dass diese geteilten Systeme bzw. Services einwandfrei miteinander kommunizieren und Daten austauschen. Ein gutes Beispiel sind Webservices. Es ist notwendig, Webservices detailliert zu dokumentieren, die man auch in der Wartungsphase immer wieder benötigt. Wenn die Webservices für Software-internen Gebrauch gedacht sind, reicht in der Regel eine Swagger-Oberfläche. Hier kann also auf ein detailliertes Text-Dokument verzichtet werden. Wenn jedoch z.B. eine API öffentlich zur Verfügung gestellt wird, die von fremden Organisationen und Softwarelösungen verwendet werden soll, ist es notwendig, eine sehr detaillierte Text-Dokumentation zu erstellen, die auch den Kontext erklärt.
5. Wie oft kann sich die Inhalt der Dokumentation ändern? Ist eine kontinuierliche Pflege notwendig?
Beispiel: Da sich die dokumentierten Inhalte einer Softwareversion (Release) ständig ändern können, muss auch die dazugehörige Dokumentation (z.B. Changelog) kontinuierlich nach jedem Versionsupdate gepflegt werden.
Beispiel: Klassen und Funktionen werden üblicherweise ständig angepasst oder erweitert. Daher macht es wenig Sinn, diese außerhalb des Codes zu dokumentieren – die Pflege würde extrem aufwendig und teuer. Auch hilft eine externe Dokumentation den Entwicklern nicht wirklich, den Code leichter zu verstehen. Besser sollten kurze Informationen und Referenzen direkt im Code als Kommentar erfasst werden. Generell gilt, dass Klassen und Funktionen am häufigsten geändert werden, auch in der Wartungsphase. Die Softwarearchitektur und technischen Konzepte dagegen nicht.
6. Wer soll die Dokumentation erstellen und pflegen?
Beispiel: Für die Dokumentation der Anforderungen ist in der Regel der Kunde verantwortlich. Bei der kontinuierlichen Pflege der Dokumentation können andere Stakeholder unterstützen. Beispielsweise können Designer oder Entwickler nicht-funktionale Details für eine Anforderung ergänzen, oder ein Business-Analyst kann die Akzeptanzkriterien aktualisieren.
Für die Erstellung und Pflege einer Dokumentation ist in den gängigen Projektmanagementmethoden keine feste Rolle vorgesehen. Meiner Erfahrung nach, sollten am besten die leitenden bzw. organisierenden Personen (z.B. Projektmanager, Scrum Master) die Doku-Schreiber auswählen, sofern sie das Projekt in allen Phasen begleiten. Nur sie kennen alle Stakeholder. Sie können eine phasenübergreifende Sichtweise ermöglichen und interdisziplinäre Stakeholder zusammenbringen. Wie bereits erwähnt, ist für die Dokumentation eine gemeinsame Entscheidung wichtig, die eine interdisziplinäre Kollaboration voraussetzt. Auch für die Zuständigkeit der Erstellung und der Pflege ist ein gemeinsames Verständnis sehr hilfreich.
7. Wo wird die Dokumentation abgelegt?
Beispiel: Ein Team mehrerer Personen, die diverse Skills mitbringen, unterschiedliche Hintergründe haben und verschiedene Tools benutzen, tendiert oft dazu, verschiedene Ablageorte für die Dokumentationen zu verwenden. Bei gjuce kommen zahlreiche Tools zum Einsatz. Z.B.: inVision für Design-Entwürfe, Jira für diverse Anforderungen, GitLab für Repositories, Lucidchart für Charts und Diagramme, MySQL Workbench für DB-Diagramme, Balsamiq für Mockups. In der Regel wird dazu geraten, dass alle Stakeholder einen zentralen Ablageort nutzen, um verschiedene Arten der Dokumentationen zusammenzustellen.
8. Wie geht man mit der Abrechnung der Doku-Aufwände gegenüber dem Kunden um?
Beispiel: Selbst in einem sehr kleinen Softwareprojekt sollten die Anforderungen, die Systemarchitektur, wichtige Code-Stellen als Kommentare, sowie Workflows für Development und Deployment dokumentiert werden.
Zunächst ist es wichtig, dem Kunden transparent verständlich zu machen, dass Dokumentation ein integraler Bestandteil jeder Software-Entwicklung ist. Im Rahmen der Projektplanung sollte anhand obiger Kriterien kalkuliert werden, wie viel Dokumentationsaufwand entstehen kann. Auch wenn es am Ende nur ein Schätzwert ist, sollten typische Dokumentationsarbeiten zu Beginn besprochen und deren Finanzierung geklärt werden.
1 Fußnote: J. Ludewig und H. Lichter stellen in ihrem Buch...