Jira and Confluence are highly configurable to align with your project documentation needs. This is a great strength, because as you transform your practices you will want to adapt the tools for continuous alignment with how you actually work. So how do you make a strong start, while still retaining flexibility for the future?

A simple structure

The tooling structure detailed here supported a team of developers and analysts making changes to an extensive suite of products. We used Atlassian tools Confluence, Jira, and Bitbucket. Our goal was to have a clear, unambiguous structure for requirements and related information which made certain things didn’t get lost and you could find what you needed when you needed it. In addition, the structure was implemented with one eye on continuous improvement, for evolution towards more conventional agile product teams.

Confluence spaces

We created a series of Confluence spaces to  allow staff to collaborate on creation and use of documentation. These spaces came in two types:

  1. Capability based spaces:
    1. Project induction, FAQs, etc.
    2. How-To guides
    3. Social, personal spaces etc.
    4. Blogs
  2. Project spaces that contain:
    1. Decisions
    2. Notes
    3. Product Requirements
    4. Rationale
    5. Retrospective notes
    6. Other project specific information

We characterise a Project Space as a wrapper of all useful information needed to implement a change.

Jira integration

Alongside these Project spaces, we created two tiers of Jira projects, one for tracking changes required for projectsin a one-to-one relationship with Confluence project spaces, and one to track product changes, in a many-to-many relationship with the project tier. Each project could result in many changes to many products and products can be changed by many projects.

Issues (User-Stories, Tasks, Defects, etc.) are created from Confluence Product Requirement pages through Atlassian’s interoperability features inside the first tier Project. In turn, the necessary implementation work for that Project is broken down into issues tracked in the second tier. The tooling was customised to create a new relationship pair for linking issues between first tier and second tier-  “Implemented By” from Project to Product and “Implements” for vice-versa. An issue in the first tier (the Project tier) cannot be completed (“Done”) unless all associated issues in the second tier (the Product tier) are also complete.

Exploring a typical use case

An analyst is assigned to work in a Project. The analyst creates artefacts as part of the work that describe changes needed by the business – they do this work collaboratively inside Confluence using a bespoke product requirement template. Pertinent information is collated within a series of product requirement pages. Once implementation is almost ready to start, the analyst creates an issue in the corresponding first tier Jira project. The analyst identifies changes required to three products to satisfy the acceptance criteria, and creates issues in each of the three Jira projects in the second tier. Those issues are associated back to the issue in the first tier.

A developer can be assigned to work on implementing code changes on all three products to satisfy the issue’s acceptance criteria. They are able to view the project issue and see all necessary information through a reciprocal link to the Confluence pages.

Challenges

Any documentation structure can face difficulties. For example, wikis have a tendency to descend into chaos, and issues can be created in the incorrect Jira tier or project. By coaching the teams to use the tools with a definition of “Done“, where the work and source requirement are reviewed before any change is considered complete, we were able to scale the approach across the organisation.

clear starting structure with clear exemplars and coaching helps teams to keep the information well organised.

Additional benefits

The structure brings other advantages. The programme is able to track changes on individual products, no matter which project called for the change, and conflicting changes can be picked up early. All roles within the project have a clear area of most interest. The first tier of Jira projects manages project requirements and implementation, which is where any project manager is most interested. The second tier is where product managers track product increments. Below the second tier, links to Bitbucket map code directly to requirements.

Next steps might include:

  • smaller projects renamed as initiatives,
  • initiatives aligned to strategic goals of the organisation,
  • products aligned to teams,
  • establish a single program and then organisation backlog,

and the structure is set up to aid the ongoing transformation to greater agility and more modern practices.