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 in requirements, the project team must read all 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 portions 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.
This is how it looks 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 done with a plugin Multi Excerpt, which allows you to insert parts of the same document into different documents.
The text of the changed part of the requirements is framed by the MultiExcerpt macro. If the change is small (for example, a single number or a small sentence has changed), we add some text to the macro around this change so that the reader understands the context.
On the document page with new functionality:
Add the Multiexcerpt include macro. In it, we indicate which block from which page should be inserted:
The finished feature page in edit mode looks something like this:
In order to grasp and immediately understand the status of all requirements for new functionality at a glance, we have 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”.
And the macro “Report on page properties” is added to the feature page, it specifies the feature label, as well as a list of properties that must be displayed.
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, most likely it will become known at a later stage (for example, during testing) and will affect the release timeline. Unfortunately, we have had such precedents.
To track the impact of functional modules on each other and not to 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.
- We find all functional modules that may be affected by changes in the requirements for the Person card
- Add the corresponding tag to them (in our case, this is #person)
- Add the “Search Results” macro on the Requirements page for the Person card
In edit mode, it looks like this:
And the reader sees this:
Versioning requirements by release
Confluence paired with a plugin Scroll Versions allows for each new release to make a separate branch of requirements, 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
To work with comments, we use the plugin Talk…
Its pros:
- 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 relevance of the schemes had to be maintained in two places, and this required 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 Allows 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.
- PParallel editing of one document and automatic conflict resolution. 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.
This is how it looks in the document in edit mode:
Then we insert a link to this anchor in the document (Insert -> Link -> Advanced):
- To create a link to another document, before the name of the anchor, we indicate the name of the document to which you want to refer, then the symbol “#” and after it the name of the anchor.
- To create a link to the current document, just indicate the “#” symbol in front of the anchor name.
IN official documentation it is said that a link to the title can be made without the Ancor macro, but then the link will lose functionality when the title text changes.
Text background color
Make a custom visual design of the text, in particular, highlight the background of the text
filling, you can use Markdown-markup (Insert -> Markup, Markdown).
<span style="background-color: rgb(202,225,255);">текст</span>
Substitute the RGB code for the color you want.
For fans of automation, there is another life hack: you can first change the color of the text in the visual editor, and then, in the mode of editing the source code of the page, using regular expressions, make the auto-replace of the HTML markup for highlighting the text with a fill color.
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 edit mode of the page source code.
That’s all. Ask questions in the comments!
PS The 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 by this link…
Article author: Ilshat Gabdullin g1r
