Welche Dokumente Sie in einer agilen Umgebung verfassen sollten

Vor, während und nach Projekten flammt immer wieder die Diskussion über die Dokumentation auf. Welche Dokumentation sollten wir erstellen? Warum brauchen wir Designdokumente? Wie können wir sicher sein, dass wir die richtige Software erstellen, wenn wir kein vollständiges Funktionsdesigndokument haben? Wie können wir überprüfen, ob wir das bekommen haben, wofür wir bezahlt haben, wenn das Funktionsdesigndokument nicht mit der tatsächlich erstellten Software übereinstimmt? usw. usw. usw.

Worin besteht das Problem überhaupt?

Die wichtigste Frage der Dokumentation:

Wenn wir nicht alles dokumentieren, woher wissen wir dann, dass wir das bekommen, was wir wollen, und wie können wir überprüfen, ob wir das Richtige bekommen haben, nachdem wir das Projekt durchgeführt haben?

Natürlich impliziert die Frage eine Antwort:

Wenn wir jeden Aspekt des Projekts im Vorfeld gründlich dokumentieren, wissen wir, was gebaut werden muss, bevor wir mit der Arbeit beginnen, und wir können leicht überprüfen, ob das gelieferte Produkt den ursprünglichen Anforderungen entspricht.

Das Problem ist natürlich, dass die Antwort bereits in der Frage enthalten war!

Arten von Dokumentation

Meiner bescheidenen Meinung nach gibt es im Bereich der (Software-)Projekte zwei Arten von Dokumenten, nicht mehr und nicht weniger:

1. Dokumente, die alle Teammitglieder für die Arbeit an dem Projekt benötigen.
2. Dokumentation, die mit dem Endprodukt ausgeliefert wird.

Lassen Sie uns diese beiden Typen untersuchen und versuchen, herauszufinden, was wann und in welcher Tiefe erstellt werden muss.

Dokumente, die alle Teammitglieder für die Arbeit an dem Projekt benötigen

In einer idealen Welt würden wir gerne alle Arbeiten von einer Person zur anderen durch direkte Kommunikation übergeben; im Gespräch miteinander, vorzugsweise im selben Raum. Es gibt jedoch viele Situationen, in denen es bequemer oder besser ist, etwas zu dokumentieren. Sei es, dass wir Wissen durch Zeit und Raum transportieren müssen, dass wir etwas aufschreiben müssen, weil wir dazu neigen, es zu vergessen, oder dass das Aufschreiben von etwas einfach dem Denkprozess hilft.Irgendwann haben wir, die Softwareindustrie, jedoch begonnen, diese Art von Arbeitsdokumenten mit Dokumenten zu verwechseln, die mit dem Produkt ausgeliefert werden sollten. Daher die seltsame Idée fixe, dass funktionale und technische Designdokumente im Einklang mit dem eigentlichen Produkt erstellt werden sollten, das nach Abschluss des Projekts entwickelt wird. Wenn man die Leute fragt, warum sie dies tun wollen, enthalten die häufigsten Antworten Argumente wie:

• Wir müssen wissen, was gebaut wurde
• Für Wartungszwecke
• Wenn etwas nicht zu funktionieren scheint, müssen wir sehen, wie es ursprünglich gedacht war

All diese Gründe sind schlechte Gründe, um zu versuchen, ein dickes, fettes Dokument zu pflegen, das nur zu dem Zweck erstellt wurde, um mitzuteilen, was überhaupt gebaut werden soll. Nach der Fertigstellung einer Funktion und der Übergabe an die Produktionsumgebung ist jedes Dokument, das während des Erstellungsprozesses mit der Absicht erstellt wurde, diesen Prozess zu unterstützen, obsolet geworden!

Woher wissen wir, was gebaut wurde?

einfach, sehen Sie sich das Produkt in der Produktionsumgebung an!

Wie können wir die Wartung ohne Dokumentation durchführen?

Jedes Dokument, das für die Wartung benötigt wird, sollte als Teil des versandfähigen Produkts erstellt werden. Dies ist jedoch nicht dasselbe wie ein Designdokument! Die meiste Software a) hat eine nicht allzu lange Lebensdauer (5 Jahre alte Software ist ziemlich alt). Moderne Programmiersprachen machen es möglich, lesbare und für den Menschen verständliche Software zu erstellen, wodurch die Notwendigkeit einer separaten Dokumentation sinkt (der Code ist ein großer Teil der Dokumentation). Wichtig ist hier, dass Sie herausfinden, welche Art von Dokumentation für die Wartung wirklich benötigt wird. Finden Sie die Beteiligten und sprechen Sie mit ihnen! Meiner Erfahrung nach werden in der Regel ein paar Architekturdiagramme und einige unterstützende Tabellen verwendet, aber der Großteil des beschreibenden Textes wird nie (jemals!) gelesen.

Wie können wir herausfinden, was ursprünglich beabsichtigt war?

Nun ... das ist jetzt nicht wirklich wichtig, oder? Wenn ein Produkt in einer Produktionsumgebung eingesetzt wird, ist die einzig relevante Frage die: Erfüllt diese Software unsere Anforderungen? Wenn nicht, was müssen wir dem aktuellen Produkt hinzufügen oder daran ändern! Jede Debatte darüber, was ursprünglich beabsichtigt war, ist Zeitverschwendung.Offenbar haben wir Menschen diesen seltsamen Drang, dass andere uns bestätigen, dass wir Recht hatten, bevor wir uns der Kunst zuwenden, tatsächlich an einer Lösung zu arbeiten. Es ist einfach so erfrischend, wenn Sie diesen Drang loslassen und sich sofort der Kernfrage zuwenden: Müssen wir eine Änderung am System vornehmen? Sobald Sie akzeptieren, dass Dokumente, die ausschließlich zur Unterstützung des Produktentstehungsprozesses geschrieben werden, entsorgt werden, sobald das Projekt abgeschlossen und das Produkt ausgeliefert ist, können Sie hoffentlich auch anfangen, dem Drang zu widerstehen, ein solches Dokument übermäßig vollständig und 100%ig korrekt zu gestalten! Das ist genau der Grund, warum das Schreiben von Dokumenten so zeitaufwändig (und damit teuer!) ist. Wenn Sie erst einmal akzeptiert haben, dass Sie gerade genug aufschreiben müssen, um Ihre Botschaft zu vermitteln oder Ihr Gedächtnis zu unterstützen, werden Sie auch verstehen, dass Stift und Papier, Fotos von Whiteboard-Zeichnungen, Kritzeleien auf der Rückseite eines Untersetzers, Storyboards usw. für diese Zwecke ausreichen!

Dokumente, die mit dem Produkt geliefert werden

Je nach Produkt, Kunde, Installationsbasis usw. usw. ist es erforderlich, einen bestimmten Umfang an Dokumentation als integralen Bestandteil des Produkts zu liefern. Typische Beispiele sind:

• Benutzerhandbücher
• Handbücher für den Einsatz
• Wartungshandbücher (für die Bedienung der Software)
• Technische Dokumentation (für die Pflege der Codebasis)

Die Art der Dokumentation, die mit dem Produkt versandt werden soll, muss lange vor der Fertigstellung des Produkts festgelegt werden. Schließlich ist das Produkt erst dann fertig, wenn alle Teile des zu liefernden Produkts fertig sind! In der Regel müssen Sie sich also darauf einigen, welche Dokumentation mit dem Produkt geliefert werden soll, bevor Sie mit der Erstellung beginnen. (Vor allem, wenn es sich um eine Kunden-Lieferanten-Beziehung handelt). Wenn Sie sich darauf geeinigt haben, mit welcher Dokumentation das Produkt ausgeliefert werden soll, können Sie immer noch kreativ sein, was die Form der Dokumentation angeht. Sie können ausführliche Benutzerhandbücher schreiben oder Sie können mehr 2.0-Techniken wie Screencasting zur Aufzeichnung verwenden. Letzteres ist billiger (statistisch gesehen etwa 10 Mal billiger!) und wird mit größerer Wahrscheinlichkeit verwendet. Wie auch immer die Dokumente in Ihrem Projekt geschrieben werden sollen, hören Sie bitte auf, Arbeitsdokumente, die zur Unterstützung des Prozesses benötigt werden, mit Dokumenten als integraler Bestandteil des Endprodukts zu verwechseln.