Con­fluence

Opti­maler Werk­zeug­ein­satz

Das Wiki ist ein wesent­licher Bestand­teil des Gesamt­kon­zep­tes von cards+.

Ein Wiki ist eine Samm­lung von Web-Sei­ten, deren Inhalte von den Besuchern nicht nur gelesen, son­dern auch direkt im Web-Browser bear­beitet und geän­dert werden können. Das Ziel ist, Erfah­rung und Wissen gemein­schaft­lich zu sammeln (kollektive Intelli­genz) und in für die Ziel­gruppe ver­ständ­licher Form zu doku­men­tieren.

Wikipedia

Ohne ein Wiki wird die Methode cards+ nicht gelin­gen! Confluence ist mit Sicher­heit eine gute Wahl. Durch die große Zahl an Add-Ons gibt es prakt­isch für jedes Prob­lem im Zusam­men­hang mit Doku­men­tation eine brauch­bare Lösung. Die Kom­bina­tion von Confluence und cards+ ist in der Praxis mehr­fach erprobt. Sie ver­setzt jedes agile Ent­wick­lungs­pro­jekt in die Lage, Pro­dukt­wissen schnell und in hoher Quali­tät zu ent­wickeln und ohne Hür­den allen inter­essierten Par­teien zur Ver­fügung zu stellen.

Das Wiki bil­det außer­dem das zen­trale Ver­zeich­nis für doku­men­tierte Infor­matio­nen in ande­ren Werk­zeu­gen, z.B. Spezifi­katio­nen in einem Git-Reposi­tory, Test­pläne in einem Test­manage­ment­system oder Normen, Richt­linien, Ver­ord­nun­gen, die für das Pro­dukt rele­vant sind, in einem unter­nehmens­wei­ten Doku­men­ten­manage­ment­system.

Die PDF-Datei wird mit dem PDF Embedder ange­zeigt.


Con­fluence

Doku­menta­tion agil ent­wickeln

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.


Con­fluence

Kommen­tare erfolg­reich mode­rieren

Con­fluence hat viele Funk­tionen für die Erstel­lung und Mode­ration von Kommen­taren. Es gibt grund­sätzlich zwei Wege, wie Leser Kommen­tare hinter­lassen können. Seiten­kommen­tar und Text­kommen­tar.

Ein Seiten­kommen­tar ist ein Hinweis, der sich auf die ganze Seite bezieht. Er wird zeit­lich geordnet im Anschluss an die Seite gezeigt. Der jüngste Kommen­tar ist immer der oberste Kommen­tar, der ange­zeigt wird. Jeder Seiten­kommen­tare kann beant­wortet werden und bildet so eine hierar­chisch darge­stellte Diskussion. Erledigte Seiten­kommen­tare können nur gelöscht werden.

Ein Text­kommen­tar ist eine sehr elegante Möglich­keit, wie ein Leser Feed­back zu einem bestimmten Wort oder Satz geben kann. Er muss nur einen Teil des Textes markieren und seinen Kommen­tar hinzufügen. Für Leser der Seite wird dieser Text dann hervor­gehoben. Text­kommen­tare können auch beant­wortet werden, bilden aber anders als Seiten­kommen­tare keine Hierar­chie. Erledigte Text­kommen­tare werden gelöscht oder nur gelöst. Gelöste Kommen­tare sind für Leser unsicht­bar. Ein Autor kann sie aber jeder­zeit nach­lesen.

Eine schöne Funktion von Confluence ist die Benach­richti­gung des Autors einer Seite, wenn ein Leser einen neuen Kommen­tar geschrieben hat. Der Autor ver­liert nie den Über­blick über die Kommen­tare. Er ent­scheidet aber selbst über den Zeit­punkt, zu dem er einen Kommen­tar bear­beitet. Die gleiche Funk­tion infor­miert den Leser, der den Kommen­tar erstellt hat, wenn er gelöscht bzw. gelöst wurde. Benach­richti­gungen sind auto­matisch erzeug­tes Feed­back.

Ein für alle Autoren und Leser sicht­bares Feed­back gibt das Makro “Zuletzt aktuali­siert” (engl. “Activity Stream“). Mit dem Makro werden alle Änderungen und Kommen­tare von Seiten in der Start­seite des Bereiches platziert. Durch die Ein­schränkung auf den Bereich sehen Leser nur mehr rele­vante Änderungen. So kann sich ein Leser sehr bewusst über die Ver­änderungen einer bestimmten Produkt­doku­mentation infor­mieren.