How Product Managers and Development Teams Can Work In Synch when Connecting Requirements to Stories

Following previous posts on the Radbee blog about traceability matrices and release documentation, we were asked to provide details about how to create traceable release items (i.e. Connecting Requirements to Stories). Specifically, readers wanted to know how a user requirement or a functional specification is processed and relates to development work on stories. So, in this post, we’ll dig into the details with a simple example that illustrates how traceability items connect to stories. By the time you finish reading, you’ll understand the process – and what team collaboration looks like in Jira and Confluence.

A user requirement is born

In our example, we’ll focus on a fictional company, SmashMed Ltd., and one of its product managers, “Julia” – a composite of real-life science organizations and stakeholders with whom we’ve consulted. The processes described are all based on actual situations and uses of Jira and Confluence.

Julia loves her work at SmashMed as a product owner of the company’s next-generation, AI-based blood analyzer. She loves interviewing clinicians and lab technicians and discussing their needs and wishes with the super-smart people on SmashMed’s AI and development teams. And she loves seeing how abstract concepts and ideas turn into real-life products using Agile methodology.

She doesn’t love the “paperwork,” though. All the formal documentation is unavoidable but annoying.

So there she is, fleshing out the “user requirements” for a new product. To get started, she looks at an old user requirement, the example her colleague gave her.

Julia figures this is a perfect “copy ‘n paste” requirement.

“GAL-58: User Requirement: Only authenticated users can use the device”

Notes about Jira settings:

• Configure a new issue type: “user requirement.”
• We recommend putting user requirements and functional specifications in a separate project from where the stories are managed, as access permissions are typically more restricted. For example, only product managers are allowed to edit functional specifications and user requirements.

After this, Julia will go on to write more user requirements. But for the purpose of our example, we’ll stick with following this first user requirement into the future. Let’s take a closer look at the process by which this “design input” propagates to create a “design output.”

The user requirement impacts the product development efforts

The next time Julia reviews the product development plans, she checks in with Kumar, the dev lead, about his thoughts on the authentication mechanism. Sure enough, he already has a few related stories in the development backlog:

Stories:

1. DEVT-69: Implement user account management (user directory)
2. DEVT-70: Select an active directory platform (i.e., Okta or another)
3. DEVT-71: Implement MFA authentication using SMS/OTP
4. DEVT-72: Implement password policy

Julia then uses the information in these stories to create the functional specifications that implement the user requirement. She links the functional specifications to the stories, so that the development team and she can ensure the actual implementation (stories) are in sync with the product documentation (functional specification).

She also links the functional specifications to the user requirement to indicate the traceability link between the two.

Functional Specifications:

1. GAL-59: User will authenticate using username, password, and SMS/OTP
2. GAL-60: Passwords will be at least 10 digits long and include at least one of each: small letter, capital letter, and a digit
3. GAL-61: Password will need to be refreshed every 90 days

Notes about Jira settings:

• Configure an issue type: “functional specification.”
• Define a new link type: Traceability (trace down to/trace up to).
• Use link type “relates” to designate a connection between stories and functional specifications.

Fast forward: all stories are now implemented. Julia is notified before each story is closed and defined as “done.” She then reviews the implementation and related functional specification again.

At this point, Julia does two things:

1. Verifies that the functional specification is still aligned with the actual implementation. If not, she will either update the functional specification or bounce the story back to the developer.
2. Verifies that a test exists for the story, which she can use to demonstrate that the functional specification is tested. Julia links the functional specification to the test, and thus, over the development period, each functional specification has a corresponding test.

Notes about Jira settings:

• The story workflow contains a status, “Align with specification,” which is a mandatory status before taking the story to “done.”
• Use the link type “tests” (is tested by/tests) to link functional specifications and tests.
• Use the field “fix versions” on all involved traceability issues: user requirement, functional specification, stories, and tests.

Using this process, once the development work is complete, the user requirements, functional specifications, and test scripts are ready. Julia uses Jira Snapshots for Confluence, so the Confluence pages with the traceable items are all set. (You can learn more about this in our guide about generating traceability matrices.) It’s now just a matter of running the test cycle, writing the test report, and releasing (providing no issues were found).

And voilà! Product version 1.0 is released.

Flash forward: what happens in version 5.0?

After the release of version 1.0, the user authentication area remains stable for a while. No new stories about authentication are worked on, and the same functional specifications are included in the release notes for these versions.

But over time, the company decides to change the MFA method, and, amidst new security concerns, Julia wants to use push verification instead of SMS/OTP. She coordinates with Kumar, and the result is a new set of stories and an updated functional specification:

Stories:

1. Retire MFA authentication using SMS/OTP
2. Implement MFA authentication using “Push Verification”

Functional specifications:

1. GAL-301 User will authenticate using username, password, and SMS/OTP push verification. (Modified in version 5.0, replaces GAL-59, which becomes obsolete)
2. GAL-60 Passwords will be at least 10 digits long and include at least one of each: small letter, capital letter, and a digit. (<– No change)
3. GAL-61 Passwords will need to be refreshed every 90 days. (<– No change)

The new stories will be linked to the functional specification, and the process will repeat. Before each story is closed and defined as “done,” Julia is notified. As before, she verifies that the specification writeup is correct and that test scripts are ready.

Notes about Jira settings:

• When a functional specification and a user requirement do not change between versions, then the only update you need to make is to add the latest version to the “fix versions” fields.
• When the functional specification does change, you create a new functional specification that replaces it by indicating the new version as the “fix” version of the new specification. Use a dedicated custom field or a special link type (replaced) to indicate which functional specification is replaced by which.

If you’re like Julia (and although she’s fictional, we know many product managers just like her 😉), “paperwork” can be the bane of your existence. By understanding the process of creating user stories and functional specifications and linking them to stories, it’s easier to see how your work in aligning the actual implementation with the product documentation is essential. And with our tips, hopefully, it makes your job easier, too. As always, we’re here for you if you have any questions. Don’t hesitate to contact us.