In der agilen Softwareentwicklung ist das agile Manifest ein wichtiger Kernpfeiler. Die Werte des “Manifest für agile Softwareentwicklung” lauten:

  • Individuen und Interaktionen mehr als Prozesse und Werkzeuge

  • Funktionierende Software mehr als umfassende Dokumentation

  • Zusammenarbeit mit den Kund:innen mehr als Vertragsverhandlung

  • Reagieren auf Veränderung mehr als das Befolgen eines Plans

Vor allem durch den zweiten Punkt “Funktionierende Software mehr als umfassende Dokumentation” gepaart mit der generellen “Unbeliebtheit” der Aufgabe Softwaredokumentation, herrscht In der agilen Welt oft der Irrglaube, Dokumentation sei ein Relikt aus der Zeit des Wasserfallmodells. Aber, weit gefehlt! vor allem Anwender:innen und Administrator:innen brauchen Anleitungen, vor allem bei komplexen Systemen im Business-to-Business Kontext.

Dank Normen wie der ISO/IEC/IEEE 26515:2018-12 wird deutlich, dass Dokumentation auch in der agilen Entwicklung ein fester und wichtiger Bestandteil ist. Ein Grund mehr für mich, in diesem Artikel die Notwendigkeit und die Umsetzung effektiver Softwaredokumentation in der agilen Softwareentwicklung zu beleuchten.

Inhaltsverzeichnis

Warum ist Softwaredokumentation in agilen Projekten unerlässlich?

Ein Blick in die Norm ISO/IEC/IEEE 26515:2018-12 gibt Aufschluss und stellt im Wesentlichen drei wichtige Kriterien heraus:

  1. Klare Kommunikation: Die Norm ISO/IEC/IEEE 26515:2018-12 betont, wie wichtig klare und konsistente Kommunikation zwischen allen Stakeholdern ist, um das Reagieren auf Veränderungen, die Zusammenarbeit mit dem Kunden und im Ergebnis eine anwendungszentrierte, funktionierende Software zu gewährleisten. Agile Softwaredokumentation bietet einen strukturierten Weg, Informationen zu übermitteln und zu archivieren. Damit jeder auch morgen noch weiß, was gestern gelaufen ist.

  2. Wissen konservieren: Agilität bedeutet Wendigkeit, Anpassungsfähigkeit und rasche Reaktion auf Veränderungen. Das bedeutet nicht selten, dass auch die agilen Teams sich hin und wieder verändern. Um sicherzustellen, dass Wissen nicht verloren geht und jeder schnell auf den aktuellen Stand gebracht werden kann, ist eine zentrale Dokumentation essenziell. So ist ein z.B. effektives und effizientes Onboarding gewährleistet und auch bei Rollenwechsel der Aufbau von relevantem Wissen, deutlich einfacher und für alle transparenter.

  3. Qualitätsstandards: Die Norm legt Standards für die Softwaredokumentation in agilen Softwareprojekten fest. Denn gerade dann, wenn sich alles, jederzeit und schnell verändern kann und eine flexible Reaktion auf diese Veränderungen gefordert ist, kann es oft eine Herausforderung darstellen, die Qualitätsstandards einzuhalten und die exzellente Qualität des Softwareproduktes sicherzustellen.

 

Umsetzung von Softwaredokumentation in agilen Projekten nach ISO/IEC/IEEE 26515:2018-12:

Auch hierfür empfiehlt die Norm einen “Grundprozess” an dem du dich orientieren kannst.

  1. Dokumentiere iterativ: Angelehnt an deine agile Softwareentwicklung empfiehlt die Norm, auch die Softwaredokumentation iterativ (schrittweise) aufzubauen. Beginne mit der Dokumentation von Grundlagen und erweitere diese mit jedem Sprint. Die Doku “wächst” iterativ, so wie es auch das Softwareprodukt “tut”.

  2. Ausrichtung auf die Nutzer:innen: Die Norm legt großen Wert auf nutzungszentrierte Softwaredokumentation. Dies bedeutet, dass du alles, was du beschreibst, immer auf diejenigen Personen ausrichtest, die das Produkt benutzen. Was muss die Person über die Software wissen? Wie arbeitet die Person mit dem Produkt? Welche Aufgaben führt die Person aus und vor allem: Welchen Herausforderungen kann die Person hierbei begegnen? Die Antworten auf diese Fragen münden in deiner Softwaredokumentation in Task, Concept, Reference oder Troubleshooting-Topics und beantworten immer exakt eine Frage. Meines Erachtens ist eine topicorientierte Softwaredokumentation daher unerlässlich. Eine “Sammlung” einzelner Topics bildet schließlich deine Anleitung, was uns zu Punkt 3, der Dokumentationsart bringt.

  3. Dokumentationsarten berücksichtigen: ISO/IEC/IEEE 26515:2018-12 unterscheidet zwischen verschiedenen Dokumentationsarten wie Systemdokumentation, Benutzungsdokumentation oder Installationsanleitungen. Überlege genau, welche Arten für dein Projekt relevant sind, welche Inhalte jede, für dein Projekt definierte, Dokumentationsart enthält und wann welche Dokumentationsart von der nutzenden Person herangezogen wird. Erstelle dir einen Dokumentationsplan, damit du einen Überblick behältst.

  4. Feedback einholen und nutzen: Die agile Entwicklung lebt von Feedback. Hierzu wieder das agile Manifest: “Individuen und Interaktion” sowie “Zusammenarbeit mit dem Kunden” und “Reagieren auf Veränderungen”. All das geht nur, durch stetigen Austausch und offene Kommunikation. Dies gilt auch für die Softwaredokumentation. Hol dir regelmäßig Rückmeldungen ein. Von deinem Team, den Stakeholdern und natürlich auch denen, die deine Informationsprodukte nutzen. So gehören m.E. immer auch Dokumentationsbausteine (Arbeitspakete) in einen Sprint und die Softwaredokumentation als Checkpoint in eure Definition-of-Done (DoD). Wird das Produkt getestet, so gehören auch Testfälle für die Softwaredokumentation in den Prozess. Automatisiert und toolgestützt oder manuell mittels z.B. Umfragen oder Usability-Tests, hängt wiederum stark von deinen Umgebungsvariablen im Projekt ab.

  5. Tools und Standards: Die Norm gibt keine spezifischen Tools vor, natürlich nicht. Die Bandbreite der Toollandschaften ist daher in der agilen Softwareentwicklung breit gefächert. Von modernen Wiki-Systemen, wie z.B. Confluence über Ansätze wie Docs-as-Code bis hin zu Component Content Management Systemen (CCMS) in Verbindung mit Content Delivery Portalen leben wir, je nach Projektanforderungen, unterschiedliche Konstrukte bei unseren Kund:innen. Alle haben ihre Vor- und Nachteile und stoßen an ihre Grenzen. Doch dazu mehr im Folgenden Abschnitt.

 

Welche Tools eignen sich besonders für die agile Softwaredokumentation?

Ein zentrales Konzept, das in der modernen Softwaredokumentation immer mehr an Bedeutung gewinnt, ist „Docs-as-Code“. Dieses Konzept lehnt die Softwaredokumentation sehr stark an den gleichen Kontext an, in dem auch der Softwarecode erstellt wird. Speziell in Projekten, die viele Softwareentwickler:innen im Dokumentationsprozess involvieren, ist das praktisch, denn die Softwaredokumentation nutzt in großen Teilen das gleiche Tooling wie die Softwareentwicklung.

Was ist Docs-as-Code?

„Docs-as-Code“ bedeutet im Kern: Dokumentation wird genauso erstellt und behandelt wie der Quellcode:

  • Die Softwaredokumentation wird in Texteditoren geschrieben, oft mit leichtgewichtigen Markup-Sprachen wie Markdown oder reStructuredText.

  • Änderungen in der Softwaredokumentation werden mittels Versionskontrollsystemen, wie Git oder Subversion, verfolgt.

  • Die Softwaredokumentation wird mit Tools wie Sphinx oder Jekyll direkt aus dem Quelltext automatisch in eine ansprechende Dokumentation umgewandelt und ausgegeben werden.

  • Die Dokumentation kann über Continuous Integration (CI) und Continious Delivery (CD) Tools wie z.B. Jenkins, Travis CI oder GitLab CI automatisch generiert und ausgeliefert werden. Auf dem gleichen Weg, wie auch das Softwareprodukt selbst.

 

Wie sieht ein Docs-as-Code Prozess aus?

Auch hier lehnt sich der Prozess der Softwaredokumentation sehr stark an die Entwicklungsprozesse an:

  1. Versionskontrolle: Wie beim Quellcode auch, werden Änderungen in der Software Dokumentation nachverfolgt. So wird die Historie gewahrt und Änderungen sind leicht nachvollziehbar und können bei Bedarf auf zurückgespielt werden. D.h. du kannst jederzeit auf ältere Versionen zurückgreifen und so recht “einfach” auch Projekte betreuen, die in unterschiedlichen Versionen bei diversen Kund:innen im Parallelbetrieb laufen.

  2. Peer Review: Das vier Augen Prinzip in der Softwareentwicklung, welches die Überprüfung von Codeänderungen ermöglicht, kann auch zur Überprüfung der Softwaredokumentation herangezogen werden. Das Vorgehen ist bekannt und meist etabliert. Dadurch ist die Einstiegshürde gering. Auch ein “Peer Programming” bzw. in der Doku eher ein “Peer Editing”, also das gemeinsame Arbeiten an einer Dokumentationsbasis, ist in agilen Softwareprojekten sehr schnell durch das bekannte Vorgehen aus der Softwareentwicklung umgesetzt. Ein wichtiges Werkzeug, wenn es darum geht Fehler zu vermieden und die Qualität sicherzustellen.

  3. Automatisierung: Bei Änderungen am Code oder der Softwaredokumentation kann automatisch eine neue Version der Dokumentation generiert und publiziert werden, da die Dokumentation gleichwertig in die CI/CD-Pipelines integriert ist.

  4. Single Source of Truth: Die Informationen zum Softwareprodukt und zum Code, liegen dort, wo auch der Code zu finden ist. Das ist sehr nah beieinander und hat den Vorteil, dass Änderungen am Code, die sich auf die Softwaredokumentation auswirken sehr schnell erkannt und ebenfalls nachgezogen werden können. Das sorgt für konsistente und aktuelle Informationen. Vorausgesetzt, dass die Prozesse vernünftig aufgestellt sind und auch gelebt werden.

 

Ist Docs-as-Code der einzig sinnvolle Ansatz in der agilen Softwaredokumentation?

Ganz klares: Nein! Docs-as-Code, wenn auch flexibel und in erster Linie charmant, da sehr nah an der Softwareentwicklung, hat seine Grenzen. Vor allem in großen Softwareentwicklungsumgebungen, mit vielen Produkten, starker Varianz, dem Bedarf an Mehrsprachigkeit und dem Wunsch nach “intelligenter” sowie höchstgradig nutzungszentrierter Bereitstellung von Informationen für die anwendenden Personen, reicht die “Leichtgewichtigkeit” von Docs-as-Code meiner Erfahrung nach nicht mehr aus. Hier können vor allem Component-Content-Management Systeme (CCMS) ihre Joker ausspielen.

Docs-as-Code vs. Component-Content-Management-Systeme (CCMS): Vor- und Nachteile

Was ist ein Component-Content-Management-System (CCMS)?

Ein Component Content Management System oder abgekürzt CCMS ist ein vorrangig für die Technische Kommunikation entwickeltes Content Management System (CMS), welches es ermöglicht, Inhalte in wiederverwendbaren Komponenten zu speichern und zu verwalten. Dies auf einer modularen Ebene, welche die Inhalte in kleine “Bausteine (Topics)” zerlegt, damit diese Flexibel in unterschiedlichen Konstellationen für diverse Informationsprodukte, medienunabhängig verwendet werden können. Aber wie steht es im Vergleich zu Docs-as-Code? Hier ein Überblick über die Vor- und Nachteile beider Ansätze:

Vor- und Nachteile der beiden Ansätze im Vergleich

Docs-as-Code – Vorteile:

  1. Integration in Entwicklungsprozesse: Docs-as-Code ist ein entwicklungsnaher Ansatz für die Softwaredokumentation. Die Doku, wird wie Code behandelt und lässt sich dadurch nahtlos in bestehende Entwicklungsprozesse und -werkzeuge integrieren.

  2. Einfacher Einstieg: Es braucht nicht viel, um mit Docs-as-Code zu beginnen. Ein Editor mit Markup-Language sowie ein Versionskontrollsystem eurer Wahl reicht bereits aus. Für beides ist zudem das Know-how im Unternehmen bereits vorhanden, d.h. der Lernaufwand hält sich im Rahmen.

  3. Kollaboration: Tools wie GitHub fördern die Zusammenarbeit und ermöglichen Peer-Reviews sowie gemeinsame Bearbeitung.

  4. Automatisierung: Durch die Nähe zu CI/CD-Prozessen kann die Bereitstellung der Anleitungen zu eurem Softwareprodukt leicht automatisiert werden.

 

Docs-as-Code – Nachteile:

  1. Skalierbarkeit: Bei sehr umfangreichen Dokumentationsprojekten kann der Ansatz an seine Grenzen stoßen.

  2. Fehlende spezialisierte Funktionen: Für bestimmte Anforderungen wie Übersetzungsmanagement oder ausgefeilte Content-Reuse-Strategien kann es an spezialisierten Funktionen fehlen, bzw. müssen diese mit entsprechender Entwicklungskompetenz ausgebaut und etabliert werden. Dies hat zur Folge, dass der Gesamtprozess meist deutlich fehleranfälliger wird.

 

Component-Content-Management-Systeme – Vorteile:

  1. Wiederverwendung von Inhalten: CCMS ermöglichen eine feingranulare, modularisierte Speicherung und Verwaltung von Inhalten, die in verschiedenen Dokumenten wiederverwendet werden können.

  2. Zielgruppenspezifische Publikation: Inhalte können basierend auf verschiedenen Kriterien und für unterschiedliche Zielgruppen zusammengestellt werden. Ein weiterer Vorteil ist, dass die Systeme hierfür bereits alle Funktionen mitbringen, die eine nutzungszentrierte Bereitstellung auch für Menschen ermöglichen, die keine Kompetenzen in der Softwareentwicklung aufweisen können.

  3. Übersetzungsmanagement: Viele CCMS haben integrierte Übersetzungstools oder Schnittstellen zu Übersetzungsdiensten.

  4. Strikte Workflow-Steuerung: CCMS bieten oft ausgefeilte Werkzeuge für die Workflow-Verwaltung und Qualitätssicherung in der Softwaredokumentation.

 

Component-Content-Management-Systeme – Nachteile:

  1. Komplexität: Die Einrichtung und Verwaltung eines CCMS kann komplex und zeitaufwändig sein.

  2. Kosten: Sowohl in Bezug auf Softwarelizenzierung als auch die Schulung der Redakteur:innen können erhebliche Kosten entstehen.

  3. Lernkurve: Es kann eine Weile dauern, bis sich Teams mit den spezifischen Tools und Prozessen eines CCMS vertraut gemacht haben.

  4. Flexibilität: Während CCMS in ihrer spezifischen Domäne sehr mächtig sind, können sie in Bezug auf Integration und Anpassung an individuelle Prozesse weniger flexibel sein. Auch hier ist wieder spezifisches Know-how gefragt, welches z.B. die Anbindung an CI/CD-Tools sicherstellt.

 

Fazit

Sowohl Docs-as-Code als auch CCMS haben ihre Stärken und Schwächen in der agilen Softwaredokumentation. Während Docs-as-Code besonders für Entwicklerteams geeignet ist, die eine enge Integration von Code und Dokumentation suchen, bietet CCMS leistungsstarke Funktionen für große und komplexe Dokumentationsprojekte. Die Entscheidung hängt letztlich von den spezifischen Anforderungen und Präferenzen deiner Teams, der Projekt- und Produktstrukturen als auch der Zielgruppen ab.