In this blog I describe our Living Documentation Theme for Greenpepper in Confluence.
Evolving a living documentation as a single source of truth helps maintaining a shared understanding of requirements and features of a software product. It guarantees a consistent and up-to-date documentation of the software system.
In the last years a couple of tools have evolved to help developing such documentation systems. The most known ones are:
- FitNesse: one of the oldest tools. It is an open source Wiki around the FIT Framework, that allows online creation and editing of executable specifications in the Wiki-Markup. In the last edition , FitNesse was provided with a helpful rich text editor, making the editing much easier for non technical people.
- Cucumber: is an interpreter for executable specifications written in the Given-When-then pattern. It is open source too, and is rich with extensions and plugins.
- Concordion: it supports writing executable specifications in HTML. The connection to the automation is done using HTML attributes, which makes it easy for non technical writers to edit their specifications without needing to respond to any limitations by the BDD Tool.
- Robot Framework: ” is a generic test automation framework for acceptance testing and acceptance test-driven development (ATDD). It has easy-to-use tabular test data syntax and utilizes the keyword-driven testing approach. Its testing capabilities can be extended by test libraries implemented either with Python or Java, and users can create new keywords from existing ones using the same syntax that is used for creating test cases.”
- Greenpepper: is a plugin for Atlassian Confluence and/or XWiki that makes it possible to write executable specifications in those Wikis.
In our current project we have decided to use Greenpepper for evolving our living documentation. The reasons for that are multiple:
- The first reason was that we are already using Confluence as our knowledge management system.
- Confluence is also easy to use for non technical users and much more powerful than FitNesse.
- It was important for us to avoid introducing another tool for that purpose.
- The major advantage is that it allows us to use Confluence for the executable specifications.
- Greenpepper supports all FIT syntaxes, and supports the Given-When-Then format too.
- Extending it is also easy and makes it much more powerful.
A very weak point (from our point of view) of greenpepper is the packaged theme. It is simple, green ….(!!!), and is missing a very important feature we use very often in confluence: the left side navigation provided by the the standard confluence documentation theme.
Here is how the default Greenpepper Theme looks like:
Because the documentation theme of confluence is open source we decided to extend it so that it supports Greenpepper Scripts and macros.
And here´s the result !
Our living documentation has now the same layout as the rest of our documentation, and we can navigate through it much easier.
All we need to do is to install the plugin and select it for the living documentation space:
Get it for free !
If you are interested in our living documentation theme just drop me an email , we would provide it for you for free !