Communardo Software GmbH, Kleiststraße 10 a, D-01129 Dresden
0800 1 255 255

Konzepte schreiben mit Confluence und JIRA – ein Proof of Concept für’s Anforderungsmanagement

Ein großer Teil unserer täglichen Arbeit besteht in der Konzeption und Abstimmung der Anforderungen unserer Kunden.  Als Basis für die Implementierung und Anpassung von Software im Rahmen eines Projektes ist dieser Schritt unerlässliche Grundlage für jedes weitere Vorgehen im Projekt.

Derzeit werden alle Konzepte bei Communardo auf Basis einer Wordvorlage geschrieben. Die Verwaltung der Anforderungen erfolgt in JIRA, eine Schnittstelle zwischen JIRA und Word existiert derzeit nicht. Das Vorgehen ist deshalb wie folgt: alle Anforderungen werden direkt im Word-Dokument geschrieben und dort manuell nummeriert. Eine Übertragung der Anforderungen ins JIRA erfolgt anschließend ebenfalls manuell – meist nur mit Verweis auf das Word-Konzept um so eine Doppelpflege zu verhindern.

Als Atlassian Platinum und Enterprise Expert haben wir uns das Ziel gestellt, den vorhandenen Prozess zu verbessern, indem die Anforderungserfassung direkt in JIRA erfolgt, ohne dass dafür Mehraufwände für das Anforderungsmanagement bei der Erstellung von Konzepten entstehen.

Wir haben deshalb anhand eines Projektes einen Prototypen mit Confluence und JIRA gebaut um wichtige Erfahrungen zu sammeln. An dieser Stelle möchten wir nun unsere ersten Praxiserfahrungen weitergeben. Eine Demoumgebung werden wir bald zur Verfügung stellen.

Zielstellung

In erster Linie wollten wir natürlich die Erfassung der Anforderungen verbessern sowie die Abstimmungsaufwände im Rahmen der Konzepterstellung sowohl innerhalb des Teams, als auch mit unseren Kunden minimieren. In Verbindung mit den durch Confluence und JIRA bereitgestellten Möglichkeiten der Kommunikation und Interaktion erschien dies als sehr gut umsetzbar.

Die meisten Konzepte bei Communardo enthalten neben den ganzen allgemeinen Texten zwei große inhaltliche Komponenten: Anwendungsfälle und zugehörige Anforderungen. Die Anwendungsfälle beschreiben wir in textueller Form sowie mit UML Anwendungsfalldiagrammen bzw. -szenarien. Anforderungen hingegen erfordern projektspezifisch bestimmte Informatioen und ziehen konkrete Implementierungsaufgaben und gegebenenfalls auch Tests nach sich. Somit wird für alle Anforderungen eine einheitliche Erfassung und ein wiederkehrender Ablauf benötigt – das ultimative Kriterium, diese in JIRA zu verfolgen. Also unterteilten wir alle Inhalte nach dem folgenden ganz einfachen Schema:

"Prosatexte" 	-> 	Confluence
Anforderungen	-> 	JIRA

Lösungsansatz

Um zum einen den initialen Aufwand gering zu halten und zum anderen technologische Abhängigkeiten zu minimieren, sollte das Konzept weitestgehend mit Boardmitteln von Confluence und JIRA erstellt werden. Natürlich sind wir um einzelne Erweiterungen nicht herum gekommen, darauf gehe ich in den Kapitel „Zusätzliche Plugins“ und „Benutzerdefinierte Makros“ näher ein.

Lösungsbescheibung

Rahmenbedingungen

Die Basis für diese Implementierung ist jeweils ein JIRA und ein Confluence System. Theoretisch können auch ältere Versionen genutzt werden, jedoch empfehlen wir hier ganz klar JIRA 5.2 und Confluence 4.3 oder jeweils aktuellere Versionen. Diese beiden Systeme müssen per Anwendungsverknüpfung miteinander verbunden werden. Zusätzlich müssen beide Systeme die gleiche Nutzerbasis besitzen, beispielsweise per Active Directory Anbindung oder indem JIRA als Benutzerverzeichnis für Confluence genutzt wird. Für das Konzept ist zum einen ein einzelnes JIRA Projekt, zum anderen ein separater Confluence Bereich vorzusehen.

Strukturierung der Lösung

Aufgabe von Confluence

Confluence ist das führende System zum Betrachten des Konzeptes inkl. der Stuktur und aller Inhalte sowie der Verwaltung von Struktur und Prosatexten.

Es werden alle Rahmenbedingungen des Konzeptes sowie die Anwendungsfälle erfasst. Die Struktur wird anhand einer Wiki-Seiten-Hierarchie sowie von Überschriftenebenen in den Wiki-Seiten in Confluence abgebildet. Nach Notwendigkeit können beliebige Ebenen von Unterseiten erstellt werden. Die Prosatexte sind Inhalte von Wiki-Seiten, z.B. die Einleitung, Anwendungsszenarien, Anwendungsfälle, Beschreibung von Stakeholdern usw. Die Nummerierung der Überschriften wurde entweder im Seitentitel oder den einzelnen Überschriftenebenen in der Seite manuell abgebildet. Nebenstehende Grafik zeigt exemplarisch eine solche Struktur.

Die in JIRA verwalteten Anforderungen werden in den Wiki-Seiten zum Lesen eingebunden. Neue Anforderungen können auch aus Confluence heraus in JIRA erstellt werden.

Aufgabe von JIRA

JIRA ist das führende System für die Verwaltung von Anforderungen. Dies umfasst sowohl die inhaltliche Beschreibung inklusive grundlegender Formatierung, als auch den Lebenszyklus der Anforderung. Durch die Anwendungsverknüpfung ist an jeder Anforderung ersichtlich, welcher Wiki-Seite aus Confluence diese zuzuordnen ist. Anforderungen können untereinander verknüpft werden.

Zusätzliche Plugins

Um die Usability zu erhöhen schlagen wir folgende zusätzliche Plugins vor:

  • Prozesseditor: Zu einem Lösungs- oder Fachkonzept gehören auch verschiedene Arten von Grafiken. Dies können zum einen einfache Mockups zur Visualisierung von Designvorschlägen oder Eingabemasken sein, zum anderen werden häufig z.B. Aktivitätendiagramme zur Spezifizierung von Prozessabläufen verwendet. Confluence bietet hier in der Standardkonfiguration lediglich die Möglichkeit, Grafiken über den Editor als Bild im Text einzufügen. In JIRA ist es noch etwas komplizierter: hier können Anhänge nur mit Wiki-Markup im Text platziert werden. Mit Plugins wie Balsamiq Mockups, Gliffy, Diagramly und anderen besteht nun die Möglichkeit, diese Informationen direkt in den Confluence-Seiten oder JIRA-Issues zu erstellen und zu bearbeiten. Im Gegensatz zu einer Arbeit mit Word ist dies ein großer Vorteil, da so die beiden Arbeitsschritte Erstellung und Verwaltung direkt in Confluence bzw. JIRA vorgenommen werden können.
  • Bereichsvorlage: Für unseren Prototypen haben wir in Confluence einen Bereich als Vorlage für das Konzept hinterlegt. Damit ein Nutzer diesen Bereich inkl. der vorhandenen Seitenstruktur nutzen kann, empfehlen wir den Einsatz des Copy Space Plugins.
  • Optimierung Export: Für eine Verbesserung der Exportmöglichkeiten und Optimierung des Designs kann das Scroll Office Plugin eingesetzt werden.
Benutzerdefinierte Makros

An einigen Stellen sind wir allerdings mit Boardmitteln und den genannten Plugins nicht ganz ausgekommen. Um dennoch eine leichtgewichtige Lösung zu schaffen wurden einige benutzerdefinierte Makros entwickelt. Diese dienen bspw. der kompakten Erstellung und Anzeige von Anforderungen (d.h. JIRA Vorgängen) in einer Tabelle, ermöglichen die Erstellung eines ansprechendes Inhaltsverzeichnis und Abbildungsverzeichnis sowie die Bereitstellung eines Suchfeldes für JIRA .

Eine genauere Beschreibung dieser Makros erhalten Sie gerne auf Anfrage.

Stolpersteine

Einige Aspekte eines klassischen Konzeptes stellten sich erst im weiteren Verlauf der Evaluierung als potentiell hinderlich heraus:

  • Kopfzerbrechen bereitet uns noch die komplette Versionierung eines Konzeptes. Grund dafür ist allerdings, dass wir intern bei Communardo unsere Projektdokumente mit SharePoint verwalten. SharePoint stellt neben der Versionierung auch einen check out/check in Mechanismus zur Verfügung. Ohne SharePoint gibt es auch für Word-Konzepte nur die Möglichkeit jede Version als einzelne, entsprechend benannte Dateien abzulegen. Erst die Zusammenarbeit von Word und Sharepoint schafft hier Abhilfe.

    In Confluence werden einzelne Seiten zwar bei jeder Änderung als neue Verison gespeichert, es existiert jedoch nur durch Kopieren eines kompletten Bereichs oder durch den Export der Inhalte die Möglichkeit, das Konzept als Ganzes zu einem gewissen Stichtag zu archivieren. Der Nachteil dabei ist, dass sich die Versionen nicht miteinander vergleichen und wiederherstellen lassen. Wir haben uns vorerst für die einfachste Lösung entschieden und werden für jeden wichtigen Zwischenstand des Konzepes einen Export des gesamten Bereichs als PDF Dokument erstellen. Layoutanpassungen der hierfür genutzten Vorlage lassen sich z.B. mit dem Plugin Scroll PDF Exporter umsetzen. Mit dem Plugin Scroll Office ist auch ein Export nach Word-Dokument mit Layoutanpassungen möglich.

  • Die in Microsoft Word oft genutzte Überarbeitungsfunktion sowie die Vergabe von Kommentaren an einzelnen Textstellen fehlt uns auch. Änderungen an Confluence-Inhalten lassen sich nur über einen Versionsvergleich herausfinden. JIRA bietet für Issues ebenfalls eine Historie an. Kommentare zu einem Kapitel werden in Confluence immer am Ende einer Seite bzw. in JIRA am Ende einer Anforderung angezeigt. Eine Markierung und Kommentierung einzelner Texte ist so nicht vorgesehen. Ob dies in der Praxis wirklich problematisch ist, wird die Arbeit mit dem Prototypen zeigen. Einen Ansatzpunkt zur Erweiterung der Systeme um die genannte Funktionalität stellt unter Umständen das Plugin ‚Talk‘ für Confluence dar.
  • Werden JIRA Vorgänge in Confluence eingefügt oder erstellt, so ist in der Bearbeitungsansicht der Seite nur der Vorgangsschlüssel, aber nicht die Zusammenfassung und Beschreibung des jeweiligen Vorgangs sichtbar. Da aber alle Anforderungen als JIRA Vorgänge erstellt werden besteht so die Notwendigkeit, die aktuelle Seite zu speichern um einen Überblick über bereits erstellte Anforderungen zu gewinnen.
  • Ein Überblick über das gesamte Konzept kann mit diesem Setting nur über einen vollständigen Export angeboten werden. Der übliche Lesefluss in einem Arbeitsdokument ist jeweils nur im Rahmen einer Wiki-Seite möglich.
  • Auf den ersten Blick ist es etwas gewöhnungsbedürftig, dass man für die Suche nach Anforderungen und Prosatexten zwei verschiedene Eingabefelder für die Suche hat. Im Praxistest hat sich das bisher jedoch nicht als Showstopper erwiesen. Zukünftig könnte man hier allerdings überlegen, eine förderierte Suche über beide Systeme anzubieten.

Fazit

Wir finden das Ergebnis sehr gut (Lächeln). Unser Hauptziel – die Optimierung des Prozesses der Anforderungserfassung sowie die Verbesserung der Qualität der Anforderungen in JIRA haben wir ganz klar erreicht. Der Prototyp hat uns gezeigt, dass man mit moderatem Aufwand eine sehr gute Vorlage erstellen kann, die trotz der genannten zu klärender Punkte sofort einsatzfähig ist. In einem ersten Test haben wir bereits erfolgreich ein Konzept erstellt und uns entschlossen, dieses Verfahren nach Absprache auch mit Kunden einzusetzen. Ob und welche unserer Bedenken in der Praxis eine Rolle spielen werden, wird der Feldversuch zeigen.

Besonders hilft uns die tiefe Integration beider Systeme. So können wir nun aus Confluence heraus Anforderungen in JIRA erstellen und sparen uns damit doppelten Pflegeaufwand. Ein weiterer Vorteil dieses Ansatzes ist das parallele Arbeiten an dem Konzept in unterschiedlichen Kapiteln durch mehrere Nutzer. So können wir jetzt auf Wiki-Seiten bzw. auf Anforderungsebene zeitgleich arbeiten ohne uns gegenseitig zu behindern.  Mit Hilfe der integrierten Kommnikationsmöglichkeiten (Mentions, Kommentare) lässt sich die Zusammenarbeit super organisieren und sich damit Abstimmungsaufwände und zugehörige Reaktionszeiten wesentlich verringern.

Auch die Tatsache, dass es mit JIRA nur eine Quelle für Anforderungen gibt, erleichtert das weitere Projektvorgehen immens. Diese können dann für die weitere Projektarbeit durchgängig genutzt werden und enthalten alle wichtigen Informationen zur Anforderung. Zusätzlich bieten JIRA-Workflows ein einheitliches Projektvorgehen für alle Anforderungen – z.B. wenn Abstimmungsprozesse eingehalten werden müssen.

Und zuletzt sind wir uns sicher, auch für die unter „Stolpersteine“ zusammengefassten Punkte eine Lösung zu finden. Schließlich sind wir nicht umsonst Atlassian Platin Experts (Zwinkern)

Wir sind nun auf Feedback und Reaktionen gespannt und werden mit Sicherheit ab jetzt viele Konzepte ausschließlich mit JIRA und Confluence erstellen. Auch mit Ihnen?

Nachtrag: Anforderungsmanagement mit JIRA und Confluence selbst ausprobieren!

Wenn Sie das beschriebene Szenario einmal in der Praxis sehen möchten, können Sie sich in unserem Demonstrationssystem registrieren und somit das Zusammenspiel von JIRA und Confluence für diesen Anwendungsfall selbst einschätzen.

Das angesprochene System finden Sie unter folgender Adresse: https://www.communardo.de/confluence/display/kwik/Konzepte+im+Wiki+Projektraum

Wir freuen uns über Feedback, weitere Anregungen oder einfach einen kurzen Austausch dazu 🙂

 

Hallo Herr Toussaint!

Sie beschreiben ein interessantes Szenario. Ich stehe vor einer ähnlichen Aufgabe:

Ich möchte Anforderungsdokumente erstellen, die neben Erläuterungen auch use cases enthalten.
Das Dokument baue ich in Confluence auf. Nun möchte ich an einer Stelle einen use case einfügen, den ich mit JIRA verwalten möchte. Der „Prosa“-Teil des use cases bleibt aber in Confluence.

Wenn ich nun ein jira-issue erzeuge, so möchte ich auf der dazugehörigen Confluence-Seite dessen Summary und Description sehen – ohne dass ich copy-paste anwende. Sie beschreiben diese Anforderungen in Ihrem Post auch – allerdings kann ich nicht erkennen, wie Sie das gelöst haben. Wie haben Sie das umgesetzt?

Vielen Dank und viele Grüße,

Ulf Schröder

Avatar Andre Schlegel

Hallo Herr Schröder,

wenn Sie Confluence und JIRA miteinander verknüpfen, dann können Sie einfach in Confluence ein JIRA-Ticket hinzufügen und geben lediglich die ID an. Der Status und der Name wird stets aktuell im Confluence angezeigt. Das bewirkt auch, dass man direkt zu dem JIRA-Ticket springen kann. Umgekehrt erhält das Ticket automatisch einen Link auf die Confluenceseite.

Hallo Herr Schröder,

Um das von Ihnen beschriebene Problem zu umgehen und redundante Daten zu vermeiden haben wir ein Benutzermakro für Confluence geschrieben welches exakt dieses Szenario ermöglicht. Den Quellcode haben wir (zumindest an dieser) Stelle bewusst noch nicht bereitgestellt, ggf. werden wir dies aber noch nachholen.

Gerne können Sie mich oder auch meine Kollegen zu dieser Thematik kontaktieren, an einem Erfahrungsaustausch sind wir natürlich ebenso interessiert.

Viele Grüße,
David Toussaint

Hallo Herr Toussaint!

In ihrem Artikel geben sie an, dass sie auch Benutzermakros in Confluence geschrieben haben, auch zur Erstellung eines Abbildungsverzeichnisses.
Da ich zur Zeit vor einem ähnlichen Problem stehe und noch keine zufridenstellende Lösung gefunden habe, wollte ich sie um eine nähere Becshreibung bitten.
Konkret möchte ich ein Abbildungsverzeichnis erstellen, welches mir im PDF Export angezeigt oder sogar erst erstellt wird.

Vielen Dank und viele Grüße

Simon Scherer

Hallo Herr Scherer,

Ich habe Sie diesbezüglich per Email kontaktiert. Gerne können wir dazu weiter in Kontakt bleiben.

Viele Grüße,
David Toussaint

Hallo Herr Toussaint,

Sie erwähnten eine Demoumgebung.
Da wir in Projekten mit Jira vor ähnlichen Themen stehen, wäre die Frage ob Ihre Demoumgebung z.V. steht um ein solches Szenario zu sichten.

Viele Grüße

Markus Lorenz

Hallo Herr Lorenz,
das Demosystem hierfür steht in unserem Supportportal bereit: https://www.communardo.de/confluence/display/kwik/Konzepte+im+Wiki
Hierfür müssen Sie sich allerdings einen (kostenfreien) Account anlegen, dann können Sie sowohl den JIRA-Teil, als auch den Confluence-Teil nutzen.
Gerne können wir dieses Szenario auch im Rahmen eines kurzen Telefonates einmal gemeinsam besprechen. Kontaktieren Sie mich hierfür ruhig.
Viele Grüße,
David Toussaint

Kommentar hinterlassen


Pin It on Pinterest