Agile Dokumentation strategisch planen: Mythen, Praktiken und Ziele

Was nicht dokumentiert ist, hat nicht stattgefunden.

Während sich die Welt mehr für das Endprodukt interessiert und sich auf die Spezifikationen und Feinheiten konzentriert, ist der "Prozess" für sie weniger anregend geworden.

Hinter den Kulissen ist es der Prozess, der alle in den Schatten stellt. Und ein wichtigerer Teil des Prozesses ist die Dokumentation. Im traditionellen Softwareentwicklungssystem beginnt und endet die Dokumentation mit dem Projekt.

Während der Zweck der Dokumentation gleich bleibt, ist der Prozess der Softwareerstellung agiler geworden.

Wenn sich der Entwicklungsprozess ständig ändert, ohne einem festen Plan zu folgen, wie stark beeinflusst das die Dokumentation? Welche Best Practices sollten bei der Dokumentation eines agilen Produkts befolgt werden?

Und vor allem: Sollte Dokumentation überhaupt Teil eines Projekts sein, in dem es keine umfassende Planung oder Strategien gibt?

Lassen Sie uns das näher betrachten.

Was sind agile Praktiken?

Die agile Softwareentwicklungsmethodik befürwortet adaptive Planung, evolutionäre Entwicklung und kontinuierliche Integration und zielt auf die schnelle Bereitstellung von Änderungen in der Software ab. Der Ansatz zur Softwareentwicklung besteht darin, Anforderungen zu berücksichtigen und zusammenzuarbeiten, um ein Produkt zu schaffen, das auch die neuen Kundenbedürfnisse erfüllt.

Die Betonung von "auf Veränderungen reagieren" anstelle von "einem Plan folgen" mag Sie für einen Moment verwirren. Es könnte den Eindruck erwecken, dass es überhaupt keine Planung gibt. Es ist jedoch eher eine adaptive Planung. Agile ermöglicht es Unternehmen, angesichts der volatilen und mehrdeutigen Natur des Marktes neuere Ideen und Strategien zu entwickeln.

Agile schafft die starre Struktur ab und implementiert einen kürzeren Plan mit einem Umfang von Iterationen, die ersetzt werden können, ohne Aufwand für eine detaillierte Planung zu verschwenden.

Einige seiner besonderen Merkmale sind kontinuierliches Feedback, Sprintplanung und kürzere und schnellere Release-Zyklen, die für mehr Transparenz im Projektmanagement sorgen.

Arten der Dokumentation

Da jeder Entwickler und jedes Projekt anders ist, gibt es verschiedene Arten von Dokumentationen, die von den Teams gepflegt werden können. Insbesondere die Softwaredokumentation kann in folgende Kategorien unterteilt werden:

Produktdokumentation

Sie enthält Informationen über das Produkt, das sich in der Entwicklung befindet, und Anweisungen, die ausgeführt werden müssen. Angesichts der vielfältigen Aufgaben kann sie weiter unterteilt werden in:

Systemdokumentation: Dieses Dokument beschreibt das System selbst und enthält Daten zum Design, Architekturbeschreibungen, Programmquellcode und Hilfemodelle.

Benutzerdokumentation: Dies umfasst Tutorials, Benutzerhandbücher, Handbücher zur Fehlerbehebung, Installations- und Referenzhandbücher für die Endbenutzer des Produkts.

Prozessdokumentation

Dokumente, die während der Entwicklungs- und Wartungsphase benötigt werden, fallen unter die Prozessdokumentation. Zum Beispiel Projektpläne, Zeitpläne, Berichte, Standardtests, Protokolle und ähnliches.

Wartungsdokumentation

Oft sind die Pläne in Agile flexibel und erfordern möglicherweise eine ständige Wartung mit detaillierten Berichten, die Unstimmigkeiten bekämpfen. Diese Art der Dokumentation ist sinnvoll, um die Bedürfnisse von Audit- oder Wartungsteams zu erfüllen.

Diskussion und Dokumentation

Der ständige Austausch zwischen den Teams spielt ebenfalls eine entscheidende Rolle bei der Verfeinerung der Prozesse und damit der Dokumentation. Mit jeder neuen Idee, die ins Spiel kommt, wird das Dokument prägnanter und nähert sich dem Ziel.

Was ist agile Projektdokumentation?

Agile Dokumentation als Begriff oder Praxis existiert nicht. Sie wird lose verwendet, um die aktive Dokumentation zu bezeichnen, die erstellt wird, während das Softwareprodukt mit agilen Praktiken erstellt wird.

Obwohl es sich um eine interne Dokumentation handelt, gibt es keinen definierten Standard für ihre Erstellung.

In einem traditionellen Projekt-Setup (dem "Wasserfall") ist die Dokumentation genauso wichtig wie das Endprodukt, wobei die Teammitglieder oft darauf warten, dass die Dokumentation abgeschlossen ist, bevor sie ein Projekt verlassen.

"Dokumentation sollte niemals ein Selbstzweck sein, und jede Dokumentation sollte jemandem in irgendeiner Weise einen Mehrwert bieten."

In einem schnelllebigen Umfeld erfordert Agile einige wichtige Entscheidungen in der Dokumentation, wie z. B. die Ermittlung von:

1. Die Art der zu erstellenden Dokumentation
2. Wer am meisten davon profitiert
3. Der Wert, den sie bieten würde
4. Wie dieser Wert am effizientesten und effektivsten erzeugt werden kann, ohne unnötigen Overhead zu verursachen.

Die oben genannten Regeln umfassen alle Formen der Dokumentation, einschließlich:

1. Interne Dokumentation, die nur innerhalb des Projektteams verwendet wird
2. Externe Dokumentation, die von Personen wie Stakeholdern außerhalb des Projektteams verwendet wird
3. Jede andere Dokumentation, die für die laufende Schulung und Unterstützung des Projekts verwendet wird

Diese Faktoren und ihr Ansatz stehen in völligem Gegensatz zu dem Dokumentationsansatz, der in einer traditionellen Umgebung verfolgt wird, in der ein Großteil der Dokumentation als erforderliches Ergebnis zur Erfüllung von Prozessanforderungen obligatorisch sein kann.

Da Agile auf einem intelligenteren und schnelleren Prozess zur Softwareentwicklung und -bereitstellung basiert, wird die Dokumentation in Agile von den Programmierern erstellt.

"Aber denken Sie daran, Programmierer schreiben keine Dokumentation"

Ein umstrittener Befürworter der agilen Methodik: Wie unterscheidet sich die agile Dokumentation von der traditionellen?

Benutzerorientierte Dokumentation vs. interne Dokumentation

Die Benutzerdokumentation ist, wie der Name schon sagt, direkt auf den Endbenutzer (oder Kunden) bezogen und für diesen erstellt. Sie vermittelt ein Know-how des Produkts und erklärt den Benutzern, wie sie es verwenden können. Es kann sich um ein Benutzerhandbuch, eine Online-Hilfe oder eine Reihe von FAQs handeln. Sie werden von Marketing- und Vertriebsmitarbeitern erstellt.

Die interne Dokumentation oder Entwicklerdokumentation ist nicht Teil des Endprodukts und nur wenige Personen haben Zugriff darauf. Sie bezieht sich darauf, wie oder warum das Produkt gebaut wurde, so wie es ist. Sie umfasst im Wesentlichen technische Spezifikationen wie Codes und Sequenzdiagramme usw. Sie werden von Architekten, Business-Analysten oder Entwicklern erstellt und von ihren Kollegen in der Gegenwart oder Zukunft verwendet.

Den Mythos brechen. Agile Dokumentation ist wichtig

Der Zweck jedes Produkts ist es, dem Benutzer ein Höchstmaß an Benutzerfreundlichkeit zu bieten. Immer.

Ohne jeden Zweifel.

Als Entwickler ist Ihr Code für Sie selbsterklärend (da Sie ihn erstellt haben), aber es kann für andere ein Albtraum sein, die Komplexität zu verstehen, wenn sie in Ihrer Abwesenheit Änderungen vornehmen. Unter all den anderen Mythen rund um die agile Entwicklungsmethodik gibt es einen, der am wichtigsten ist, nämlich den rund um die Dokumentation.

"Aber es gibt keine Dokumentation in Agile".

Agilisten schreiben tatsächlich Dokumentation. Die DDJ-Umfrage Modeling and Documentation survey aus dem Jahr 2008 ergab, dass agile Teams genauso wahrscheinlich wie traditionelle Teams lieferbare Dokumentation wie Benutzerhandbücher, Betriebsdokumentation usw. schreiben.

Die hastig hingekritzelten Post-its bieten keinen Mehrwert für diejenigen, die später versuchen, die Software zu verstehen. Dies ist in der Tat ein schwieriges Problem (kein Dokument).

Der Zweck der agilen Dokumentation ist es, den Produktentwicklungsprozess transparent zu halten und die Spezifikationen, Codes und Änderungen darzulegen.

Da die agile Methodik Teams dabei unterstützt, auf die Unvorhersehbarkeit der Softwareerstellung zu reagieren und sich an die kommenden Bedürfnisse gemäß den Anforderungen anzupassen, bietet die Dokumentation eine große Hilfe, um die Software robust zu halten.

Die Dokumentation des Prozesses und der Codes trägt zur Lebensdauer Ihrer Software bei.

Wenn Sie eine Dokumentation erstellt haben, prüfen Sie, ob sie für Ihre Teamkollegen ausreichend ist. Bietet sie demjenigen, der sie in ein paar Jahren warten muss, einen Mehrwert? Reicht sie für einen Betriebsingenieur aus, der versucht, um Mitternacht Dinge zu reparieren?

Agile soll anpassungsfähig sein. Das bedeutet, dass jede Änderung, sobald sie vorgenommen wurde, dokumentiert werden muss.

(In der agilen Methodik) kann die Entwicklung selten zu einem früheren Zeitpunkt zurückkehren, um Änderungen vorzunehmen, und funktionale Designs und Dokumentation (von Codes) werden umso wichtiger.

Aber welche Art von Dokumentation sollte erstellt werden?

Scott Ambler, ein kanadischer Softwareentwickler und Autor, erklärt in seinem Essay "Just Barely Good Enough Models and Documents: An Agile Core Practice", dass agile Dokumentation "gerade gut genug" sein sollte und dass zu viel oder umfassende Dokumentation in der Regel zu Verschwendung führen würde. Da Entwickler detaillierter Dokumentation selten vertrauen, weil sie in der Regel nicht mit dem Code synchronisiert ist, kann zu wenig Dokumentation auch Probleme für Wartung, Kommunikation, Lernen und Wissensaustausch verursachen.

Das Hauptziel Ihres Teams ist immer die Entwicklung von Software, aber das nächste Ziel ist es, diese Bemühungen nicht zu verschwenden. Natürlich ist es wichtig, qualitativ hochwertige Nischensoftware zu entwickeln, die die Bedürfnisse Ihrer Stakeholder erfüllt, aber es ist auch wichtig sicherzustellen, dass die Personen, die nach Ihnen kommen, sie warten und verbessern, betreiben und unterstützen können.

Vorteile der agilen Dokumentation

Angesichts der vielen Medien, der unterschiedlichen Zwecke für verschiedene Stakeholder und des Schreibstils kann die Dokumentation überwältigend sein.

Hier sind die Vorteile, die Entwickler nutzen können, um zu kommunizieren und gleichzeitig Codes, Skripte und Tests zu ergänzen:

1. Stellt sicher, dass sich alle auf derselben Ebene befinden
   
   Da jeder in einem anderen Tempo arbeitet und ein anderes Verständnisniveau hat, können häufige Sprints das Gedächtnis einiger derjenigen, die an dem Projekt arbeiten, beeinträchtigen, ganz zu schweigen von denen, die es später warten (die sich des Prozesses nicht bewusst sind).
   
   Daher ist es wichtig sicherzustellen, dass sich alle auf derselben Ebene befinden.
    
2. Macht die Software robust
   
   Kurzsichtigkeit kann Entwickler in die Irre führen, zu glauben, dass wenig oder keine Dokumentation zu den Codes ausreicht. Dinge, die trivial erscheinen, könnten sich für andere als wichtig erweisen.
   
   Es sind diese kleinen Dinge, die sicherstellen, dass die Dinge verstanden werden, und die auch helfen, zu beurteilen, ob die Implementierung sinnvoll ist, und versehentliche Komplexität aufzudecken.
   
   Stellen Sie sich vor, der Wartende kann nicht verstehen, warum das Problem so schwer zu lösen ist, weil niemand versteht, wo das Problem überhaupt liegt.
   
   Wenn Sie das Dokument auf dem neuesten Stand halten, können Sie Fehler und Probleme leicht verfolgen.
    
3. Schafft einen besseren Geist unter den Teammitgliedern
   
   Wenn die Dinge gut dokumentiert sind und die Verfahren und Details ordnungsgemäß dargelegt sind, entsteht ein besseres Verständnis des Projekts. Ein transparenter Prozess schafft ein besseres Einfühlungsvermögen unter den Teammitgliedern in Bezug auf die Verantwortlichkeiten, die sie teilen.
   
   Einfühlungsvermögen hilft auch, ein besseres Verständnis der Herausforderungen zu schaffen. Und die Arbeit an einer Software ohne jegliche Anleitung kann nervenaufreibend sein.
   
   Die Schaffung einer Umgebung, in der sich die Menschen bei der Änderung der Software geführt und sicher fühlen, muss immer willkommen sein. Dies ist besonders hilfreich beim Onboarding und bei der Fehlerbehebung, z. B. bei "Readme"-Dateien oder Checklisten für Dinge, die noch nicht automatisiert sind.

Bonus-Tipp: Stellen Sie sicher, dass jedes Stück einen Mehrwert für das Unternehmen darstellt, nicht nur in Form von Dokumentdateien.

Mögliche Herausforderungen bei der agilen Dokumentation

1. Keine Erfahrung im Schreiben: Programmierer sind nicht dazu bestimmt, Dokumentation zu schreiben. Mangelnde Erfahrung im Schreiben kann sich als eine der Herausforderungen herausstellen. Entwickler sind gut im technischen Teil, aber sie sind viel zu oft hilflos, wenn es darum geht, ihn zu beschreiben. Eine mögliche Lösung hierfür ist die Einstellung von jemandem mit technischem Hintergrund.
    
2. Zu viele Informationen zum Teilen: Im Zusammenhang mit dem ersten Punkt kann dies beim Schreiben ein großes Hindernis sein. Das Identifizieren und Eliminieren redundanter Informationen ist schwierig, insbesondere wenn sie von Ihnen geschrieben wurden. Stellen Sie sicher, dass nur prägnante und relevante Informationen Teil der Dokumentation sind.
    
3. Zu früh begonnen: Einmal geschrieben, ist das Umschreiben nur eine Verschwendung von Mühe. Etwas Geduld beim Schreiben zu üben, kann hilfreich sein, insbesondere wenn es darum geht, minimale Dinge zu schreiben, die maximale Ergebnisse liefern.
    
4. Verstreute Daten: Unter Berücksichtigung der Vielfalt des Teams müssen die Dokumentationsnotizen an einem Ort aufbewahrt werden und zugänglich und transparent sein.
   
   Um ein klares Durcheinander zu vermeiden (Oxymoron, ich weiß), stellen Sie sicher, dass die Papier-/E-Dokumente in regelmäßigen Abständen an einem Ort zusammengeführt werden. Alle Mitarbeiter sollten sich die Zusammenstellung von Zeit zu Zeit ansehen. Es wird ihnen helfen, sich an das Hauptziel zu erinnern. Darüber hinaus werden sie über alle Renovierungen auf dem Laufenden gehalten.

Bewährte Verfahren zum Schreiben agiler Dokumentation

Das Dokumentationsverfahren ist hier in zwei Teile unterteilt, um ein besseres Verständnis des Schreibens der Dokumentation vor und nach dem Schreiben zu erhalten.

• Verstehen Sie den Umfang des Dokuments, bevor Sie eintauchen
   
  • Dokument mit einem Zweck
    
    Das Wichtigste, worauf Sie bei der Erstellung eines Dokuments achten müssen, ist die Ermittlung des Zwecks. Wenn der Zweck ein Dokument mit einem klaren, wichtigen und unmittelbaren Ziel Ihrer gesamten Projektbemühungen erfordert, erstellen Sie nur dann eines. Der Zweck kann immer kurz- oder langfristig sein und andere Stakeholder als die Entwickler einbeziehen.
     
  • Identifizieren Sie die Bedürfnisse der Dokumentation
    
    Sobald der Zweck definiert ist, suchen Sie die beteiligten Stakeholder. Sie sollten eng mit der potenziellen Zielgruppe dieses Dokuments zusammenarbeiten, um seine Benutzerfreundlichkeit zu verbessern.
    
    Identifizieren Sie, woran sie glauben und was sie benötigen, und planen Sie dann entsprechend, um die Informationslücke zu schließen.
    
    Indem Sie die Bedürfnisse Ihrer Kunden verstehen, können Sie prägnante und ausreichende Dokumentation liefern und gleichzeitig einen herausragenden Wert schaffen.

• Effektive Dokumentation schreiben

  • Agile ist nicht statisch

    Der Großteil der Informationen, die in traditionellen Spezifikationsdokumenten erfasst werden, wie z. B. Anforderungsspezifikationen, Architekturspezifikationen oder Designspezifikationen, kann als "ausführbare Spezifikationen" erfasst werden.

    Wenn Sie agile Dokumentation verwenden, müssen diese effektiv mit detaillierten Spezifikationen und Änderungen geschrieben werden, beginnend mit der Entwicklung bis hin zur Bereitstellungsphase. Sie sind nicht statisch.

  • Halten Sie es prägnant und präzise

    Die agile Strategie besteht darin, unnötige Schritte zu vermeiden, wobei nur die relevantesten Dinge befolgt und dokumentiert werden. Sobald die Vision des Dokuments erstellt ist, ist es einfach, redundante Informationen zu vermeiden.

    Bevorzugen Sie ausführbare Spezifikationen gegenüber den theoretischen Ideen. Versuchen Sie, die Überschneidung von Informationen zu minimieren.

    Dokumentieren Sie Ihre Entscheidungen nur, wenn es Alternativen gibt und Sie eine Erinnerung daran benötigen, was hinter diesen Entscheidungen steckt. Da sich ein bestimmtes Verfahren wiederholen kann, kontrollieren Sie den Drang, es vollständig zu dokumentieren.

    Schreiben Sie für die jeweilige Situation, die gerade gut genug ist, um den Gesamtzweck zu erfüllen.

  • Halten Sie das Dokument auf dem neuesten Stand, warten Sie nicht

    Die Methodik konzentriert sich auf die Beherrschung des kontinuierlichen Wandels. Dies erfordert die Notwendigkeit, die Dokumente so häufig wie die Echtzeitänderungen in der Software zu aktualisieren, um sicherzustellen, dass auch später qualitativ hochwertige funktionierende Software gewartet wird.

    Springen Sie nicht auf, um zu schreiben, zu früh. Warten Sie, bis die Entscheidung umgesetzt ist und es kein Zurück mehr gibt, während Sie sie zu Papier bringen.

    Stellen Sie sicher, dass die Informationen stabil und zuverlässig sind, während Sie die Kosten, die Zeit und den Aufwand für die Überarbeitung Ihrer Dokumente reduzieren.

  • Weniger schreiben, am besten schreiben

    Lassen Sie die Personen, die das Dokument später verwenden müssen, den Inhalt bestimmen.

    Da agile Teams oft vielfältig sind, ist eine Informationsüberschneidung eine mögliche Realität. Anstatt den Teil jedes Teams in Seiten und Abschnitte aufzuteilen, fassen Sie sie zu einer Tagesaktivität zusammen.

    Dies würde es ermöglichen, dass das Inhaltsverzeichnis nicht repetitiv ist und sowohl als Support- als auch als Informationsleitfaden herauskommt. Der Vorteil davon ist, dass Informationen nur an einem Ort definiert werden, wodurch die Wahrscheinlichkeit von Überschneidungen verringert wird.

Betrachten Sie Ihre Dokumentation als eine Anforderung

Im Idealfall sollte die Dokumentation während des gesamten Softwareentwicklungslebenszyklus erstellt werden. Das Schreiben von Dokumentation ist genauso wichtig wie der Prozess des Produkts. Echtzeit-Feedback trägt zu seinem tatsächlichen Wert bei.

Mit anderen Worten: Schreiben Sie wenig, holen Sie Feedback ein, handeln Sie danach und iterieren Sie.

3 Ziele mit Agile erreichen

Eine gemeinsame Basis

Oft kann ein einfacher Fehler die Ursache für Zwietracht und Meinungen sein, die aufeinanderprallen. Oder wenn eine Änderung vorgenommen werden muss, können die Teams aufgrund von Meinungsverschiedenheiten nicht den richtigen Weg einschlagen. Daher ist eine gemeinsame Basis des Verständnisses auf der Grundlage der Dokumentation für alle am Projekt Beteiligten wichtig. Jede Phase der Änderung sollte ein ausgeklügeltes System von Regeln und Logik haben. Mit der agilen Dokumentation schaffen Sie eine Basis, um solche Schlupflöcher zu beheben.

Empathie zwischen Entwicklern und Nicht-Entwicklern

Es ist allgemein bekannt, dass die Gräben zwischen den Entscheidungsträgern und den Entwicklern schwer zu überwinden sind. Oft bereitet der Mangel an Wissen bei den Projektmanagern den Entwicklern eine schwere Zeit.

In Duretti Hirpas Artikel über "Empathy Driven Development" beschreibt sie "empathischen Code" als eine Vorstellung von der Erstellung einer Codebasis mit dem Vorteil "jedes Werkzeugs, das Kontext bietet", einschließlich Dokumentation.

Der gesamte Akt der Erstellung von Dokumentation zeigt ein Gefühl der Empathie gegenüber den Teamkollegen und schafft eine Umgebung eines sicheren und geschützten Arbeitsplatzes.

Fundierte Entscheidungen treffen

Wie verwaltet man die Dokumentation für die Zukunft, wenn man so viel Wert darauf legt?

Scheuen Sie sich nicht, die Dokumentation zu verwerfen, die unnötig erscheint. Bei Agile dreht sich alles um Effizienz und die Vereinfachung der Prozesse. Unter Berücksichtigung des Wertes einer bestimmten Dokumentation durch kollaboratives Eigentum können Sie ihre Bedeutung erkennen und die Verantwortung für die Aktualisierung teilen. Diese Aktivität hilft Ihnen, das Ziel zu erreichen, Entscheidungen zu treffen, die im besten Interesse des gesamten Teams liegen.

Schlussfolgerung

Agile Entwicklungsmethoden sind definitiv die besten, die Sie bekommen können, um die besten Branchenpraktiken für die Softwareentwicklung einzuführen.

Erfahren Sie mehr über agile Prozesse und verstehen Sie, ob sie die richtige Lösung für Ihre Softwareentwicklungsbedürfnisse sind, kontaktieren Sie uns unter [email protected].

Das Ziel jeder Dokumentation ist es, ein vollständiges, eindeutiges Ergebnis und eine Aufzeichnung der eingearbeiteten Änderungen einschließlich der Endergebnisse zu liefern.

Die Dokumentation wird bei der Arbeit an einem agilen Prozess immer wichtiger.