How we use Confluence to develop product requirements

This article outlines our approaches to using Confluence as a product requirements tool. We do not pretend to be universal, but perhaps these approaches will be useful for solving your tasks that are not necessarily related to requirements development processes (maintaining user documentation, describing the internal regulations of the department, organizing a knowledge base, etc.).

All changes to the requirements for a new feature on one page

We develop complex Enterprise products that are replicated to hundreds of corporate customers. One of our products has over 100 functional modules and each module has a separate requirements document. Features of a new release, as a rule, affect several (from 3 to 20) functional modules.







To understand all the changes to the requirements, the project team must read all the documents that affect the new functionality, and in addition to that, figure out what exactly has changed in each of them. It is long and inconvenient.



To solve the problem, we made a summary document for each new functionality. It contains only the changed parts of the functional module requirements. At the same time, if something changes in the original document, this will be automatically reflected in the summary document.







Something like this in real life:







Now the project team only needs to read one document to understand all the changes. The analyst, on the other hand, "collects" the document once and does not worry that the changes that arise must be supported in two documents at once.



Technically, this is implemented using the Multi Excerpt plugin , which allows you to insert parts of the same document into different documents.





In order to grasp and immediately understand the status of all requirements for new functionality at a glance, we added an automatically updated table to the summary document with a list of related requirements, their statuses, responsible analyst and a brief description of the changes.







This is done using the standard macros "Page Properties Report" and "Page Properties".

Trace requirements

Changes in the requirements for one functional module may require changes in other modules. If you forget about related changes during the requirements development stage, it is likely that this will become known at a later stage (for example, during testing) and will affect the release deadline. Unfortunately, we have had such precedents.



To track the impact of functional modules on each other and not forget about related changes in requirements, we use the functionality of tags (tagging). It turns out a kind of tracing of requirements, but with a large step: at the level of functional modules, and not atomic requirements.







With more than a hundred functional modules and their interconnection, even such a large tracing step allowed us to significantly reduce the number of cases when an analyst in the process of developing requirements for a new functionality forgets to take into account related requirements.



To do this, we use the standard Confluence tagging functionality and the Search Results macro.

Versioning requirements by release

Confluence paired with the Scroll Versions plugin allows you to make a separate branch of requirements for each new release, while all documents in each release have their own change history. Switching between release versions is done in a couple of clicks. In addition, you can compare the requirements of both different releases and different versions of the same document within the same release.







This is how switching between release versions looks like in real life:

Commenting

We use the Talk plugin to work with comments .







Its pluses:

• You can see comments and reply to them in document editing mode. This is very convenient when you need to make changes to requirements based on the review results
• There are no problems with parallel commenting (especially if you plan to switch from MS Word + Sharepoint: you do not need to block the entire document), the requirements can be reviewed simultaneously by the entire project team
• If a comment is left on a feature page in a Multi Excerpt block, it automatically appears in the original requirements document

In addition, it has nice features such as highlighting comments with different colors, managing visibility for different users and likes.



We abandoned the standard commenting functionality in Confluence, because it had disadvantages that were critical for us:

• Cannot be used in conjunction with the Multi Excerpt plugin
• Comments are not visible in document editing mode
• Comments disappear if you change the text to which they were attached

Creating charts and mockups

First, we used MS Visio and exported the diagrams in bitmap format, and then loaded them into Confluence. This approach was inconvenient - the schemas had to be kept up-to-date in two places, and it took too much action.



As it turned out, Confluence has many plugins for working with all sorts of graphic objects (diagrams, diagrams, mockups, etc.). Balsamiq Wireframes for Confluence and Draw.io Diagrams for Confluence allow you to edit graphic objects without leaving Confluence. At the moment, these plugins almost completely cover our needs.

Basic features

I will briefly talk about the basic capabilities that Confluence provides (like most other wikis). In order not to retell the documentation, I will limit myself to a list of what we mainly use:

• Comparison of document versions. You can quickly understand how functionality has changed from release to release.
• P arallelnoe editing of a single document and automatic resolution of conflicts. Several people can review a document at the same time without having to wait for their turn while the document is locked for editing by another employee (as it was when we used Sharepoint and the requirements were stored in the form of Word files).
• Document templates. We have created templates for all main types of documents (functional module, feature, meeting minutes)
• Flexible capabilities of access control (up to the page level). This is convenient, for example, for outsourced employees who cannot be given access to all the requirements at once
• Export of documents in various formats. It helps a lot in those rare cases when it becomes necessary to transfer documents outside.
• Integration with JIRA. You can automatically insert task status, approvals and other information from JIRA tickets.

Migrating from MS Word

There are a few non-obvious things that you encounter almost immediately after switching from Word to Confluence.

Numbering headings

To add automatic numbering of headings, you need to frame the text with the Numbering headings macro.

Hyperlink to section

In order to refer to any part of the document or the section heading inside the document, you must first add the Anchor macro (in Russian localization it is called "Anchor"), and then add a hyperlink to it from the required part of the document.

Text background color

You

can use Markdown markup (Insert -> Markup, Markdown) to make a custom visual design of the text, in particular to highlight the background of the text with a fill.









This is not very convenient, but we have not yet found another way to select text with a fill.

Cons:

• Copying and pasting text marked in this way from the clipboard usually leads to loss of markup.
• You can change the markup only in the mode of editing the source code of the page.

That's all. Ask questions in the comments!



PS This article is based on the report "Confluence Life Hacks for Requirements Development" at the Analyst Days conference, the video version of this report can be viewed at this link .



Article author: Ilshat Gabdullin g1r