Agile Dokumentation - geht das? Ein Praxisbericht

Zugehörige Leistungen: Softwaredokumentation und Entwicklerdokumentation

Das Stichwort agil ist in der Softwareentwicklung mindestens so beliebt wie DITA in der Technischen Dokumentation. Kein Wunder: Agil und DITA konzentrieren sich auf Modularisierung und die Anforderungen der Nutzer. Dieser Artikel beleuchtet, wie agiles Dokumentieren in der Praxis funktioniert, welche Tools die Prozesse unterstützen und welche Vor- und Nachteile sich für ein Dokumentationsteam ergeben.

Was ist Scrum?

Scrum ist ein agiles Vorgehensmodell in der Software-Entwicklung, nach dem ein komplexes Produkt in Inkrementen entwickelt wird. Scrum-Teams können Produkte in kürzeren Zyklen fertigstellen und Feedback schneller einholen und einarbeiten.

Scrum basiert auf drei Grundprinzipien: Transparenz, Überprüfung und Anpassung. An die Stelle der Feinspezifikation tritt das Product Backlog, eine priorisierte Liste der gewünschten Funktionalitäten (Anforderungen) aus Anwendersicht.

Anders als bei einem traditionellen Projekt nach dem Wasserfallmodell wird am Anfang des Projekts nicht davon ausgegangen, dass alle Anforderungen umgesetzt werden können. Im Laufe eines Scrum-Projekts werden zunächst die hochpriorisierten Anforderungen umgesetzt und abgeschlossen. Der genaue Funktionsumfang des fertigen Produkts wird im Laufe des Projekts immer neu betrachtet und hängt davon ab, welche Anforderungen bereits umgesetzt wurden und wie viel Zeit und Ressourcen den Teams noch zur Verfügung stehen.

Diese Funktionalitäten werden meist als User Storys formuliert.

Während des Projekts wird immer wieder überprüft, wie viele User Storys schon umgesetzt wurden, welche noch umsetzbar sind und ob die gewählten Konzepte passen. Erweist sich ein Konzept als ungeeignet, wird es im Idealfall angepasst, bis die gewünschte Qualität erreicht ist. Erst wenn eine Funktionalität fertig entwickelt, getestet und dokumentiert ist, werden weitere Funktionalitäten in Angriff genommen.

Das Scrum-Team

Im Kern der agilen Softwareentwicklung steht das Entwicklungsteam. Es entscheidet darüber, wie Funktionalitäten aus dem Product-Backlog umgesetzt werden. Die meisten Absprachen im Team erfolgen mündlich, z.B. in Plannings und Daily Standups. Die Produktentwicklung erfolgt in kurzen Iterationen (Sprints). Am Ende jedes Sprints soll ein release-fähiges Produkt verfügbar sein. Gehört die Endbenutzerdokumentation zum Produkt, muss diese zeitgleich mit der Entwicklung fertig sein.

Herausforderungen für die Technische Dokumentation

Wie gehen die Technischen Redakteure mit den häufigen Änderungen während der Produktentwicklung um? Lässt es sich vermeiden, Texte ständig neu schreiben zu müssen?

Sind Technische Redakteure Teil des Scrum-Entwicklungsteams, sind sie stets auf dem aktuellen Stand. Doch was, wenn nicht? Oder was passiert, wenn es zum Beispiel für drei Entwicklungsteams nur einen Redakteur gibt?

Wie sollen die Redakteure Dokumentation fertig stellen, wenn bis zum letzten Sprint-Tag entwickelt wird? Und was ist eigentlich mit den Übersetzungen?

Das agile Modell als solches liefert keine Antworten auf diese Fragen. Aber es erlaubt individuelle Lösungen, solange diese den Grundprinzipien nicht widersprechen. Die folgenden Methoden können dabei helfen, das Chaos vor der Tür zu lassen.

Entwicklung in Teams

Idealerweise gibt es mindestens für die Dauer des Projekts feste Teams, sodass sich die Mitglieder aufeinander einspielen können und mit der Zeit immer effizienter als Team werden. Das Team ist als Gruppe verantwortlich für die Fertigstellung der Entwicklungsaufgaben, zu denen auch die Dokumentation gehört. Benötigt der Redakteur Unterstützung in Form von Informationen, Demos oder Reviews, müssen diese Aufwände bei der Sprintplanung berücksichtigt werden.

Mitglieder der Entwicklungs- bzw. Scrum-Teams sollten sein: Product Owner, Scrum Master, Entwickler, Mitarbeiter der Qualitätssicherung (QA) und Technische Redakteure. Je nach Organisation und Art des Produkts kommen gegebenenfalls weitere Rollen wie User-Interface-Designer hinzu.

Zusätzlich zu den Scrum-Teams gibt es möglicherweise weitere Teamstrukturen, da sich Kollegen derselben Fachrichtung, z.B. QA, Technische Redakteure und User-Interface-Designer, projekt- und teamübergreifend austauschen und über Arbeitsweisen abstimmen. Man kann die Entwicklungsteams als vertikale Teams und die fachlichen Teams als horizontale Teams begreifen.

Definition of Done

Elementarer Bestandteil von Scrum ist die Definition of Done (DoD). Die DOD ist eine Art Checkliste der Bedingungen, die erfüllt sein müssen, damit eine User Story abgeschlossen werden darf. Die Dokumentation sollte ein fester Bestandteil der DOD sein. Das heißt, ein Feature ist erst dann fertig, wenn es auch dokumentiert ist. Allerdings ist es nicht immer möglich, die tatsächliche Endbenutzerdokumentation im selben Sprint fertig zu stellen.

Als Workaround kann man für das Schreiben der Endbenutzerdokumentation eigene User Storys anlegen, die von der eigentlichen Entwicklungsaufgabe getrennt sind, aber mit dieser in Zusammenhang stehen. Die ursprüngliche User Story hat dennoch eine Dokumentationsaufgabe (Doc Task), die die Entwickler nutzen, um für die Redakteure Stichpunkte für die Endbenutzerdokumentation vorzuschreiben. Diese Doc Tasks bilden dann die Grundlage für die User Storys, die den Technischen Redakteuren zugewiesen werden.

Scrum-Meetings

Regelmäßig stattfindende Scrum-Meetings (Dailys, Planning, Retrospektiven) stellen sicher, dass alle Teammitglieder jederzeit über den Stand der Entwicklung und die weitere Planung informiert sind. Die Technischen Redakteure nehmen an so vielen dieser Meetings teil wie möglich, da sie hier die meisten Informationen für die Dokumentation erhalten und direkte Ansprechpartner für Rückfragen und Reviews verfügbar sind. Kann der Redakteur an diesen Meetings nicht teilnehmen, gibt es idealerweise einen Stellvertreter, z.B. den Scrum Master, der die Belange der Redaktion vertritt und Informationen weitergibt.

Darüber hinaus haben die Redakteure häufig weitere Regelmeetings mit den anderen Redakteuren (horizontales Team). In diesen Meetings berichten die Technischen Redakteure aus ihren Projektteams und verständigen sich z. B. auf Formulierungen, Benennungen, Struktur und Layout. 

Räumliche Anordnung

Für die räumliche Anordnung gibt es viele verschiedene Modelle. Manche Scrum-Teams sitzen im selben Raum, während andere über verschiedene Zeitzonen und Kontinente hinweg kommunizieren. Als Redakteur hat man das Dilemma, dass man sich einerseits mit den Kollegen aus der Redaktion und andererseits mit den Scrum-Teams eng austauschen muss. Ob man dazu direkt nebeneinander sitzt oder nicht, ist eine individuelle Entscheidung. Wichtig ist, dass eine direkte und einfache Kommunikation jederzeit gewährleistet ist.

User Storys

User Storys erleichtern das aufgabenbasierte Dokumentieren von Features. Sie stellen eine wichtige Grundlage für die Endbenutzerdokumentation dar, auch wenn sie sich nicht immer 1:1 in der Dokumentation abbilden lassen. Anders als manche Entwickler sind Technische Redakteure es gewohnt, neue Features aus dem Blickwinkel der Endbenutzer zu betrachten. Je mehr die Redakteure in das Schreiben der User Storys im Backlog eingebunden werden, desto besser eignen sich diese als Grundlage für die Endbenutzerdokumentation.

Fazit

Die folgenden Fragen stellten wir am Anfang des Artikels:

Wie gehen die Technischen Redakteure mit den häufigen Änderungen während der Produktentwicklung um? Lässt es sich vermeiden, Texte ständig neu schreiben zu müssen?

Die Akzeptanz von Änderungen ist ein wesentlicher Bestandteil agiler Methoden. Daher lässt es sich nie ganz vermeiden, Texte neu zu schreiben. Allerdings kann man diese Fälle auf ein Minimum beschränken, indem z.B. in den Teams darauf geachtet wird, dass die User-Interface-Designer frühzeitig in die Entwicklung neuer Features eingebunden werden und grafische Konzepte in Form von Wireframes u.Ä. erstellen, auf deren Grundlage die Dokumentation geplant wird. Geht man außerdem davon aus, dass ein Feature am Ende eines Sprints auch wirklich fertig ist und dass die Tragfähigkeit des Konzepts laufend überprüft wird, sollte die Dokumentation ebenso final schreibbar sein.

Sind Technische Redakteure Teil des Scrum-Entwicklungsteams, sind sie stets auf dem aktuellen Stand. Doch was, wenn nicht? Oder was passiert, wenn es zum Beispiel für drei Entwicklungsteams nur einen Redakteur gibt?

Daily Standups, Demos und Backlogs ermöglichen einen direkten Informationsfluss. Feedback fließt in alle Richtungen (Reviews, Retrospektiven). Als Mitglieder der Scrum-Teams haben die Technischen Redakteure Einfluss auf das Design der Software und geben Usability-Beratung. Gleichzeitig stehen sie von Anfang an für sprachliche Fragen zur Verfügung und können z. B. beim Benennen der Bedienelemente helfen (Stichwort Konsistenz).

Häufige Reviews innerhalb des Teams stellen sicher, dass alle Technischen Redakteure auf demselben Wissensstand sind. Eine stetige Anpassung der Herangehensweise ist in einer lebendigen Scrum-Umgebung essentiell.

Wichtig: Viele Teams und viele Meetings erfordern ein hohes Maß an Zeit- und Organisationsmanagement. Oft muss ein Redakteur mehrere Entwicklungsteams betreuen. Das ganze System kommt außerdem schnell aus dem Gleichgewicht, wenn die Redakteure neben dem Schreiben zusätzliche Aufgaben haben, die parallel anfallen und z.B. die Teilnahme an Teammeetings verhindern.

Wie sollen die Redakteure Dokumentation fertig stellen, wenn bis zum letzten Sprint-Tag entwickelt wird? Und was ist eigentlich mit den Übersetzungen?

Aufgrund der sequentiellen Fertigstellung von Features können Technische Redakteure schon früh mit dem Dokumentieren beginnen. Allerdings sind sie auf ein weitgehend fertig implementiertes Feature angewiesen, um es zu beschreiben. Die weiter oben beschriebenen Doc Tasks und das Verschieben der eigentlichen Dokumentation auf den nächsten Sprint helfen vielen Teams dabei, dennoch agil zu bleiben.

Einige agile Teams bereiten im Sprint neue Features konzeptionell so gut vor, dass die Redakteure die Dokumentation anhand der Konzepte schreiben können, während parallel implementiert wird. Diese Vorgehensweise stellt die Königsklasse der agilen Entwicklung dar und sollte das Idealziel aller agilen Teams sein.

Übersetzungen hingegen sind und bleiben ein Problem, für das man gegebenenfalls die Anforderungen anpassen muss. Moderne Redaktionssysteme auf XML-Grundlage und professionelle Übersetzungstools ermöglichen die sequentielle Übersetzung einzelner Module. Ein Problem aber bleibt: Was noch nicht geschrieben wurde, kann auch nicht übersetzt werden. Daher erfolgt die Übersetzung in der Regel mindestens einen Sprint später als das Schreiben der Dokumentation. Allerdings haben die Übersetzer dann das Problem, dass sie einzelne Module ohne Zusammenhang bekommen, worunter möglicherweise Qualität und Konsistenz leiden. Daher ist es durchaus legitim, mit der Übersetzung erst gegen Ende des Entwicklungsprozesses zu beginnen, sofern ausreichend Zeit dafür vorhanden ist.