Real examples of having requirements or use cases on Confluence

[Sumit Sharma]

I would like to know if any customers have used Confluence for requirements or use case documentation in a software product company context. I am aware that there is the Product Requirements blueprint, but I was hoping to have real examples of Confluence customers who managed all their requirements or use cases on Confluence, and any best practices, learnings, or points to be considered from that experience.

FWIW, we do have Jira integrated too, and I have noted Atlassian's own usage described at https://confluence.atlassian.com/jirakb/using-jira-for-requirements-management-193300521.html.

Thanks.

[G subramanyam]

Hi @Sumit Sharma welcome to the Atlassian community.

In one of my ex-projects, I have extensively used and relied on Confluence for all requirements documentation, business use cases and few RFP's.

All that I did was to first create my own tree structure with different phases of the project, written user stories in confluence, created Jira issues from that confluence page, paste the relevant mock up's/ wireframes both in-page and as attachments. I found it to be real simple both in tracking as well presenting to client.

[Patrick Haley]

Yes, we use Confluence for all UC documentation. Our page tree is as follows:

• Team and Communication - includes key contacts, meeting info, etc
• Development - general info about system architecture, guides for new dvs, infrastructure overview, integration points, data migration steps, and stuff related to UAT
• Discovery Phase - all the notes and information related to our legacy sofware before we rewrote it
• Meeting notes - self-explanatory
• Project Management - Processes for handling support and change requests, monthly project plans, etc all linked with Jira tickets
• Quality Assurance - Overview of QA environments, etc
• Requirements - The largest section that contains all system documentation and UC development; I'll outline more below this.
• Retrospectives - Internal team meeting notes after each sprint
• Trackers - Here's where we keep logs of change requests, decisions, emails, external documents such as Google Sheets, glossaries, scheduled tasks, etc
• Support - general info about support

In the Requirements where we track use cases, we break down each page by System > Module > Components. We have a UC for Viewing/Filtering/Searching Lists, then Creating/Editing/Viewing records. Each UC is typically broken down by the following:

• Goal - purpose of the UC
• Views, Actors - who can use it
• Preconditions - requirements and permissions needed to access the feature
• Entry points - Conditions for UC execution and link to the calling UC page
• Flow of Events - numbered checklist that describes the UC. Usually consists of a Main Flow and sometimes an Alternative Flow.
• Special Requirments - as needed
• UI/UX - screenshots of the on-screen elements labeled by DB column name. I don't like to link to external UI/UX tools because someone always deletes a link and then you can't view it anymore. Under UI UX we include a table with each UC. I'll add a sample table below.
• Preconditions - general description of what the user would see after the flow
• Notes - We use this to indicate what would happen if the UC results in an error e.g. display the bug report screen.

This is the UC table described above. I can't add a table here so each bullet is a column:

• ID - Just a sequential numbering system for quick reference in the UC (e.g. 1, 2, 3.1, 3.2, 4, etc)
• Element - Reference to UI/UX elements (e.g. lbl_menu_contacts, lbl_contact_types, etc).
• Type - What type of field is it (e.g. label, button, date, checkbox, etc)
• Mandatory - Y or N if the field is required
• Initialization - default value of the field. Most of the time this is blank or it might be "ticked". Sometimes we might reference data from the db such and a link to the data model.
• Rules/Dependencies - Most important column and the one that contains the most info. Any time we reference another UC, field, or external document we add a link to it. We always use the data model name for these. (e.g. When ticked the system shows in #CONTACTS_TABLE records from um_contacts where um_contacts_types.contact_type_id = '2'). um_contacts is a hyperlink to the model as is um_contacts_types.contact_type_id. Sometimes it's really simple and just says "Always visible. Sortable". 
• Referenced Data - Just links to a different table if we're pulling info from it.

Best practices I've learned: 

• Keep the DB Data Model in the Development section current
• Update the UC before coding ALWAYS
• Have the client or whoever on your team approve the UC (preferably in the comments) before implementation)
• Add special markers in the UC to show a change. We use a new color and CR#1234 to indicate that a change was made.
• Keep comments and suggested changes to UC listed as comments in Confluence. Makes it each to action them later. 

[Rina Nir]

Hi @Patrick Haley 
Thanks for the detailed "recipe" here.  Seems you have a very mature setup there.
Can you indicate if you have considered managing/documenting the UC in Jira, and if so- what where your reasons to do this in Confluence?

[Patrick Haley]

Jira is just what we use for tracking issues and managing development. Confluence is home base for business analysis. 

[Dharmesh Barot]

Hi Patrick,

Thanks for your detailed response. I'm curious how the details in the table are added to the Jira tickets. Seems like you'd either just link the ticket to the Confluence page or manually copy each column from a UC table to the corresponding ticket(s).

Please share.

[Dave Rosenlund _Trundl_]

Hi, @Sumit Sharma. We have worked with one Atlassian Solution Partner and one Customer to create webinars on this topic (see below). You might find the content useful to you and if you want introductions to the people involved you can find me on LinkedIn pretty easily.

Hope this helps,

-dave [ALM Works]

1. Webinar with RadBee - an Atlassian partner that specializes in Requirements Management for Life Sciences)
2. Webinar with Amdocs (customer) on their requirements traceability solution with Confluence + Jira

[Rina Nir]

Hi @Sumit Sharma and thanks @Dave Rosenlund _Trundl_ for the callout.

Keeping UCs in Confluence makes a lot of sense as long as you are not working in a very formal environment, where each requirement needs to have a unique ID and should be part of a traceability matrix. If you need this level of formality then I find that Jira is a much better place - albeit the editor is less good and tracking versions is more difficult (but there are solutions to that as well). The advantage you get in Jira is:

• the unique identification,
• the traceability is easily established through Jira native links
• more powerful workflow engine- which means its far easier to track the status of each requirement (ie- approved, released, etc)

If you are interested in the "formal" version of UC and requirements management, here are some more recent links (done on the footsteps of that successful webinar we have with ALM):

1. A recent recording of a presentation I gave about requirements management in Jira
2. A bunch of articles with detailed explanations of the why and how to manage requirements in Jira/Confluence:

1. Connecting stories and requirements
2. Creating and exporting traceability matrices
3. How to create release documentation
4. Why manage requirements in Jira