Methode

Doku­menta­tion agil ent­wickeln

Die Werte aus dem Mani­fest für agile Soft­ware-Ent­wick­lung bil­den das Funda­ment agiler Ent­wicklung. Mit cards+ kann auch Doku­mentation agil ent­wickelt werden. Agil Doku­mentieren bezeich­net ein schritt­weises Erfas­sen von Ent­schei­dungen und Wissen in einem agilen Ent­wicklungs­prozess. Die Struk­tur der Produkt­doku­mentation ist so gestal­tet, dass Ergeb­nisse schritt­weise mit einem geeig­neten Bau­stein gesichert werden kann. Autoren schrei­ben nur das auf, was sie jetzt wissen. Keine Wünsche. Keine Vermutungen.

Aufgrund der maß­geschnei­derten Struk­tur können Autoren trotz­dem jeden Bau­stein in kurzer Zeit abschließen. Eine wich­tige Bedingung für ein agiles Ent­wicklungs­projekt, um Doku­mentation als ein weiteres Ergeb­nis einer Iteration zu fordern. Bei agiler Ent­wicklung mit Scrum kann ein Produkt­verantwort­licher die Regel­termine von Scrum nutzen, um Feed­back auch zur Produkt­doku­mentation einzu­sammeln. Mit dem Ein­satz von cards+ gilt:

Doku­mentation wird ent­wickelt!

Eine Pro­dukt­doku­men­tation hat wie Code eine innere Struk­tur. Sie besteht aus Bau­steinen mit einem klar formu­lierten und prüf­baren Inhalt. Es bietet sich ganz ein­fach an, die Produkt­doku­mentation im gleichen agilen Prozess zu schrei­ben, in dem auch das Pro­dukt program­miert und getes­tet wird.

Eine Pro­dukt­doku­men­tation wird über die gesamte Lebens­zeit eines Pro­duktes gebraucht. Bei sehr erfolg­reichen Pro­dukten sind das Jahr­zehnte. Ein Pro­dukt ent­steht oder wächst, indem Visi­onen und Ideen eines Pro­dukt­verant­wort­lichen durch sein Team in Soft­ware trans­formiert werden. Test­pläne, organi­siert in einer Test­pyramide, sichern die Quali­tät der Soft­ware ab. Hand­bücher geben Ein­blick in die Fähig­keiten der Soft­ware, erklären den Nutzern, wie sie ver­wendet werden. In den Bau­steinen der System­beschrei­bung wird der Problem­raum des Pro­duktes beschrie­ben. Sie geben Ant­wort auf die Fragen wer, wann und warum etwas mit dem Produkt tut. Die Bau­steine der System­beschrei­bung beant­worten hin­gegen die Frage, wie das Pro­dukt reali­siert wurde. Zusammen mit den Bau­steinen des Archi­tektur­entuwrfs beschrei­ben sie den Lösungs­raum.

Eine Pro­dukt­doku­men­tation hat das Ziel, den Zustand eines Pro­dukt­inkre­mentes so exakt wie mög­lich zu beschrei­ben. Sie exis­tiert im Wiki und wird genutzt, um Spezifi­kationen und Test­pläne zu ver­öffent­lichen. Sie bildet das zen­trale Ver­zeich­nis der für das Pro­dukt rele­vanten Doku­mente.


Methode

Doku­mente nach ihrer Art unter­scheiden

Eine einiger­maße komplexe Soft­ware ohne Doku­men­tation ist für mich nicht vor­stell­bar. Ein Pro­dukt­verant­wort­licher kann oder besser muss sich über den Pro­zess der Erstel­lung einer Pro­dukt­doku­men­tation Gedan­ken machen. Im all­gemeinen Sprach­gebrauch werden Doku­mente geschrie­ben. Mit cards+ werden Doku­mente ent­wickelt. Das geht aber nicht mit jeder Art von Doku­ment.

Eine Pro­dukt­doku­men­tation ist unver­zichtbar für das Auf­recht­erhal­ten des agilen Ent­wick­lungs­prozesses und unter­stützt die Kommuni­kation in der Pro­jekt­organi­sation. Sie beschreibt Ergeb­nisse. Abstim­mungen führen zu Ent­schei­dungen. Anfor­derungen werden ana­lysiert und umge­setzt oder abge­lehnt. Auf­gaben werden erle­digt, damit ein neues Pro­dukt­inkre­ment ent­steht.

Der Begriff Pro­jekt­doku­men­tation fasst jene doku­men­tierte Infor­matio­nen zusam­men, die für das Auf­recht­erhal­ten von Pro­zessen, also Planung und Steuerung von Auf­gaben, not­wen­dig sind. cards+ bietet für die Projekt­doku­mentation keinen Bau­stein! Die Arten­viel­falt ist ein­fach zu groß. Die Bedürf­nisse der inter­essierten Par­teien sind zu unter­schied­lich. Die Lebens­dauer der Doku­mente ist oft zu gering für einen wirt­schaft­lich vertret­baren An­satz zur Standardi­sierung.


Defini­tion

Was zählt zur Projekt­doku­mentation?

Auf­gabe

Für die Erfas­sung und Steue­rung von Auf­gaben in einem Back­log bietet cards+ keinen Bau­stein an. Mit den Bau­steinen von cards+ wird jedoch wich­tiges Wissen für eine Auf­gabe recht­zeitig und struktu­riert in der Produkt­doku­mentation vorbe­reitet.

Anfor­derung

Die Ver­waltung und Bewer­tung einer Anfor­derung ist nicht Teil der Methode cards+. Das Ergeb­nis der Anfor­derungs­analyse wird jedoch mit den Bau­steinen Topic, Epic und Case ange­messen in der Produkt­doku­mentation doku­mentiert.

Abstim­mung

Im Projekt­alltag finden laufend Abstim­mungen statt. Jede Abstim­mung mit großer Trag­weite führt zu einer begrün­deten Ent­schei­dung, die es wert ist, nach­haltig doku­mentiert zu werden. cards+ bietet dafür den Bau­stein Decision an.

Richt­linie

Eine Richt­linie ist eine Verein­barungen, die die Zusammen­arbeit im Ent­wicklungs­projekten und in den Teams regelt. Ist die Richt­linie rele­vant für das Produkt, kann sie natür­lich mit den Bau­stein Spec für Kon­zepte in die Produkt­doku­mentation aufge­nommen werden.

Lasten­heft

In der agilen Welt unge­liebt, aber häufig not­wendig, um ein Gewerk zu präzi­sieren und einen Ver­trag zu schließen. Mit cards+ erstellen wir inkre­mentell eine System­beschrei­bung mit den Bau­steinen Topic, Epic und Case. Die gleichen Bau­steine können wir als Lasten­heft aus dem Wiki expor­tieren. Jeder­zeit.

Experten­schätzung

Schätzen ist ein kontro­vers disku­tiertes Thema in agilen Ent­wicklungs­projekten. Der Bau­stein Case ist eine geeig­nete Basis für die Schätz­methode »Use-Case-Points« von Stephan Frohn­hoff.


Werk­zeug

Con­fluence

Con­fluence ist die Ent­wick­lungs­umge­bung der Autoren. Es gibt Bereiche, Seiten, Seiten­vor­lagen und Anhänge in den Seiten. Die Kommen­tar­funktion gibt Autoren und Lesern die Mög­lich­keit, Feed­back zu den Inhal­ten zu geben. Mit dem Berech­tigungs­konzept können die Rollen Leser, Autor und Gärtner abge­bildet werden.

Con­fluence organi­siert Seiten in Bereiche (engl. spaces) und erfüllt damit eine wich­tige Anfor­derung von cards+ an ein Wiki. Dem Prinzip SOC folgend sollte jeder Bereich ausschließ­lich einen bestimmten Zweck ver­folgen. Aus dieser Moti­vation wird die Produkt­doku­mentation zu einem einzigen Bereich zusammen­gefasst. Nur für das Glossar wird häufig ein sepa­rater Bereich ange­legt, weil das Glossar auch für diverse Hand­bücher, Betriebs­anwei­sungen oder ganz all­gemein für das ganze Entwicklungs­projekt rele­vant ist. Mit anderen Worten: Das Glossar kann und soll auch in der Projekt­doku­mentation verwendet werden.

Die Grund­funktion von einem Wiki ist es, Seiten (engl. pages) mit Inhal­ten bereit­zustel­len. Der Sei­ten­edi­tor von Con­fluence bie­tet ein­fache Grund­funktionen. Ein Autor kann aus sechs Über­schriften­ebenen, drei Absatz­forma­ten (normal oder für Code) und kom­binier­baren Schrift­stilen (fett, kursiv, unterstrichen, durchgestrichen) wählen. Zusätz­lich bietet Con­fluence mit einer großen Aus­wahl an Makros noch weitere Gestal­tungs­mög­lich­keiten, z.B. mehr­spal­tige Texte oder Code-Blöcke.

Seiten­vor­lagen (engl. templates) erfül­len eine wei­tere wich­tige Anfor­derung von cards+. Sie sorgen für eine ein­heit­liche Struk­tur der Sei­ten im Wiki. Ohne Vor­lagen ist das prakt­isch unmög­lich. Con­fluence bietet zusätz­lich in den Vor­lagen die Mög­lich­keit, Hilfe­texte für Autoren zu hinter­legen. Diese Texte ver­schwin­den beim Ein­tippen des ersten Zeichens durch den Autor. Sehr ange­nehm.

Wie wichtig eine zentrale Ver­waltung von Medien hat, zeigt sich erst nach längerer Zeit. Eine Medien­biblio­thek ist ein Kon­zept, um Präsen­tationen, Foto­grafien (z.B. vom Flip­chart oder White­board), Abbil­dungen und Dia­gramme in ver­schie­denen For­maten an einem zen­tralen “Ort” im Wiki abzu­legen. Für die Umsetzung des Kon­zeptes legt ein Autor für jede Datei eine Medien­seite mit einem aussage­kräftigen ein­deu­tigen Titel an. Im Anhang der Medien­seite fügt er die Datei und ein Vor­schau­bild für die Anzeige im Wiki ein und ver­gibt Stich­worte, um die Medien­seite besser auf­findbar zu machen.

Die zentrale Ver­waltung von externen Links in einer Link­sammlung folgt der Idee der Medien­biblio­thek. Autoren sind durch die Link­sammlung unab­hängig von der Strate­gie der Versio­nierung in den externe Quellen. Denn externe Quellen haben oft eine abweichende, häufig inkompa­tible Stra­tegie zur Versio­nierung der Doku­mente und Unter­lagen. Selbst Unter­lagen aus Papier können auf diese Art in das Wiki integriert werden, z.B. mit den Koordi­naten in das Papier­archiv (z.B. Schrank, Ordner oder Lade). Für die Umsetzung des Kon­zeptes legt ein Autor legt für jeden Link eine Link­seite mit einem aussage­kräftigen eindeu­tigen Titel an. Im Anhang der Link­seite fügt er ein Vorschau­bild für die Anzeige im Wiki ein und vergibt Stich­worte, um die Link­seite besser auf­findbar zu machen. Die Link­sammlung können Autoren nun ver­wenden, um extern ver­waltete Doku­mente und Unter­lagen mit einem von ihnen gewählten Namen im Wiki zu ver­wenden.