Lean PPM – step 14: The concept and tools used for an agile documentation @ Digitec Galaxus

Over the last fifteen months we changed our documentation structure concept at digitec Galaxus a few times. Every change incorporated a newly discovered aspect as discussed in my previous blogs.

The tools used at Digitec Galaxus AG

The tools we use for documentation are Jira, Confluence, Signavio and our development environment (Microsoft.NET). Basically Jira is an issue tracking system, Confluence a wiki and Signavio a BPMN tool. We try to avoid file based tools like Office (Word, Powerpoint, Excel, …). Actually Powerpoint is treated as enemy. Excel is used in case we need data analysis. In this case Excel files are kept as attachments in Confluence.

All these tools offer a versioning or history concept, even for attachments. Confluence misses the concept of releases and configurations, but at least is works with a history, versions for attachments and some small idea of an archive.

I need to supply some more information for the tools so that you understand our documentation structure concept.

Jira as issue tracking tool offers the feature to change the meta model. This allows to establish new issue types and new link types between issues. With this you can model a hierarchy of issues and links between issues used for tracing. We use this feature to implement one part of our Lean Portfolio Management as discussed (see these blogs: the Kanban system step1 and step2; life cycle of an initiative).

In short: the core is a four abstraction layers Kanban system with the abstraction layers

• Theme -> Initiative -> Epic -> User Story

following a SAFe alike concept (SAFe calls the layers Theme -> Epic -> Feature -> User Story). The elements of type Initiative, Epic and User Story are implemented as linked issues in Jira.

Confluence is a wiki and collaboration system. Confluence offers the “space” feature as extension to a plane wiki. A space is a closed wiki for its own purpose. With this Confluence is a tool where you can create as many independent wiki instances as you like. You can even create wiki instance templates, i.e. if a user creates a new wiki already an initial set of pages with a predefined page structure is created and offered to the user, ready to start adding content. Confluence offers some means to navigate between spaces, so even cross-wiki collaboration can be established.

The core documentation structure concept

With all this in mind, our implementation of the documentation structure in these tool is as following

documentation structure in our tools Jira, Confluence and Signavio

The documentation structure concept holds the following elements

The Confluence space “strategic themes”

In Confluence we created one special space named “strategic themes”. You may remember, our roadmap is a wall of sticky notes following Jeff Pattons story mapping approach (see Jeff Patton’s blog and his book). This space holds all the strategic themes of our sticky wall roadmap (read about our strategic roadmap), one wiki main page per strategic theme. This page (and its sub-pages) documents the business value of this theme and our idea how to realize it step by step. One step in the development of a strategic theme again is an initiative (see life cycle of an initiative). The development of a strategic theme actually is represented by a chain of initiatives. The wiki page just lists the chain of initiatives.

As an initiative is represented in our Lean PPM as an Jira issue, actually this list is a list of links to Jira issues. As we develop a strategic theme, we develop the chain of initiatives. i.e. new initiatives maybe added or the timeline of the whole chain may change. The information of an initiative is documented in the initiative itself plus one Confluence space per initiative (see below).

The Jira issue type “initiative”

An initiative is represented as a Jira issue in our Lean Portfolio Management Kanban board (see life cycle of an initiative) An initiative documents the information about goals, strategic alignment, the project lead responsible for the initiative’s life cycle, current status, a short progress tracking statement and so on. So this is exactly the documentation that is addressing the execute manager’s interests. We try to keep this amount of information (the description attribute of the Jira issue) down to one page to read.

Additionally, an initiative holds the list of links to the Epics that represent the program level in SAFe. So any person interested in more details of an initiative has the chance to drill down to Epics level or even down to User Stories level. Last but not lease the Jira issue of type initiative links to a Confluence space (see below).

The “initiative” Confluence spaces, one per initiative

There is one Confluence space linked to every initiative in Jira. This space is used for documentation and collaboration while realizing the initiative outcome. Classical you could say, this is the “project space”. This space holds all information required to develop the initiative – except for information kept in the other element of Epcis, User Stories and in BPMN models.

Concrete this space holds meeting minutes, decisions taken, alternatives and option under discussion, agreed upon requirements (on (SAFe) feature level), the links to the BPMN diagrams of the business processes we change in this initiative and so on. An initiative space typically is the working space for project leads, business analysts, subject matter experts, product owner (read more about how we deal with these term in my blog about “Probare’s”). We agreed upon a basic page structure for this page. This recommended page structure helps readers to find information. So all meeting minutes are under the main page “meeting minutes”, all requirements under the page “requirements” and so on. This helps persons to know where to expect what type of information.

Structure of a space for an initiative

As this space is the working space as long as the initiative is under development, there is no activity anymore as soon as the initiative is implemented, reviewed and closed. We then use the archive feature of Confluence to hide it. This helps to keep the working space small and clean. As we agreed to work on max 32 initiatives in parallel (our WIP limit in our Lean PPM Kanban board) there are max about 40 initiatives visible, all the other are archived.

If we start a new initiative in the chain of initiatives driving a strategic theme, we often need to remind ourselves on a previous decision or requirement. In this case we consult our strategic theme space. There we identify the initiative in the chain of initiatives. There we click the link to the Jira issue of this particular initiative we are interested in. This initiative again holds the link to the assigned Confluence space and we have at once access to all information we are searching for.

The Jira issue type “epic”

In deed the we used to epic layer rather for organizational reasons then to store many valuable information required for development. An initiative has a relationship to one or more epics. In SAFe the counterpart of an epic would be a feature to implement that in turn is realized by a set of user stories. Actually we use the epic level a bit more general.

As we use our Lean PPM for all type change activities, an initiative is not restricted to implementing software. An initiative can be as well the reorganization of a department, an employee development program, a refurnishing of a retail shop or the maturing of a promising idea for an innovation. An initiative can be a mix of organizational tasks, concept work, software development. Additionally, our idea is that an initiative is “done” only at that point in time, when the change is rolled out to the functional department, i.e. training of employees has taken place, software has been deployed, organizational procedure changes took place and show the expected results – whatever is required to meet the DoD for this initiative.

To cover all these steps and activities and tasks as well we use the construct of an epic. An initiative can for example can be decomposed to one epic for a prototype, two feature epics to implement the software, an epic to train employees of the department in use of the software, an epic to implement new BI features to track success of the initiative and a rollout-to-department epic.

But where to keep all the information required to drive this – for example the training material used to train the users in the department? We use exactly the Confluence space of the related initiative to hold this information. As well the feature to derive user stories from for software development are documented in this confluence space and not in each epic issue. Concrete the features are documented (if needed) under the requirements page in the initiative space.

We decided for this concept as it keeps all information for an initiative focused in one place instead of spreading it over many Jira issues. As we care for that our initiative are small the amount of information is naturally limited. A well we strive to document the minimum amount of information required. We care and invest to share knowledge through agile means such as the Scrum events, a release planning meeting as used in SAFe, the CCC (card, communication, conformation) approach. We are nearly paranoid to document to many information – rather we accept some gaps in documentation than document an additional page of waste.

I hope you got the message and our concept to deal with the epic level in Jira.

The Jira issue type “user story”

Well user stories are user stories. We strive to use user stories pretty close to what many intelligent and keen persons recommend to use user stories. There is enough literature and information in form of books, blogs, conferences around. There is nothing I can really add here. Point.

The Signavio BPMN system

An e-commerce company like digitec Galaxus is business process driven. Highly automated processes are a key to success. For example, the checkout process for a customer basket is a really complicated process with many alternative flows, options and business rules. We encountered that the archived information of an initiative often is not sufficient to satisfy the need to fully understand a specific process we want to change.

Adding a new delivery type such as delivery on Saturday is a good example. This implies writing some software – but this is only one part of the story. It implies as well changing organizational procedures in logistics and accounting. Quite a set of new alternative flows in the checkout process pop-up. All these processes have to be consistent and compliant. Business process description help to keep all this consistent and not to lose control.

This is the reason we decided to build up a business process model using a BPMD tool as Signavio. If you are interested why we decided to go for Signavio, please contact me. This is out of scope for this blog. Is it more interesting how we use a business process model and how it is integrated into our documentation structure.

Core decisions about building up our business process model are:

• We do not strive to document all business processes down to all levels (one, two three). We document all business process on level one – but these are two diagrams and represents rather a table of content of our business processes then an extensive documentation.
• We do not document our business processes upfront. If we touch a business process while working in the context of an initiative, we add the according BPMN diagrams into our model and extend the model. As well we decide upon the level of detail. Some business processes are documented down to level two only, some down to a detailed level three.
• Changes of the business process model take place while working in the context of an initiative. Typically in the initiatives space (under the requirements page) the links to the changed or added BPMN diagrams are listed. This keeps requirements and models together, for example the business rules that apply within an activity of an business process model.
• BPMN diagrams are a visualization only. We do not generate or orchestrate any software. BPMN diagrams are purely for documentation purpose only. The goals is to fast and easy find, read and understand the diagrams as starting point if we want to change the process any time in the future.

We invested quite some effort to agree about our BPMN “dialect”, i.e. what we treat as a healthy level three diagram, where to stop with details or how to design specific process aspects. We covered this by external and internal training sessions enhanced by review and feedback sessions based on created diagrams.

We did not yet reach a satisfying status. Building up a business processes model that really delivers value is not an easy task – even when used for documentation only and no for orchestration of an BPMN engine. We are still on the learning path, but there is light at the end of the tunnel. Hopefully I can write a blog about a value generating business process model any time in the near future.

What we do and what works is to offer two entry points into our business processes model. One entry point is top down, i.e. if somebody wants to know how a specific business process runs in our organization, she can start at the top level diagram and drill down as far as diagrams exists. As our model still has many holes, for most processes the drill down stop on level two.

The second entry point is from aside while working in the context of an initiative. This is done by following the links listed in the initiative’s Confluence space under the requirements page. By now this is the typical way used. It is a daily work environment for our business analysts.

Getting all together

This blog describes our concept to structure documentation. Reading this it sounds like we do a lot of documentation and we act anything but not agile. Does that really follow the agile manifesto “Working Software over Comprehensive Documentation”?

I will discuss this in my next blog talking about the reasonable behind this structure – the reasonable derived from the needs of the readers of the documentation.

Many contributors within digitec Galaxus, from CEO down to software engineer developed the structure through many small steps of a continuous improvement identified in reviews, retrospectives or in the coffee corner. The existing structure will change ongoing as we identify new aspects to incorporate or when discovering existing aspects as waste. So far we agree that this structure delivers a real great benefit to all of us. We own a specific for our needs built documentation and even more important collaboration platform to drive our change initiatives.

Additionally, this concept to structure documentation does not say anything about the amount of documentation. The amount of documentation always is subject of discussion. We strive to document the least amount only – but what “least” is, is very dependent of whom you ask. Some means in our structure support to limit the amount of documtation. The two most important ones are first the WIP limit if initiatives and second the principle to archive Confluence initiative spaces as soon as an initiative reaches its DoD. So the active size of documentation is limited to the Confluence space of strategic themes, the initiatives active worked on, the business process model in Signavio, the User Stories under development and the source code base of our software systems. I personally treat this as a fair amount of documentation, especially if we strive to share most information in our heads by communication, collaboration, confirmation and feedback – and not be sending links to Confluence page via email.