How to document non-functional requirements in User Stories?

Question

I work as a business analyst in a software development firm. In my previous organisation, the development was done using waterfall and we wrote: "Business Requirement Documents" (BRDs).

In my current role, the team is using Agile Scrum and JIRA to write the user stories to capture the functional requirements etc.

My question is, how best to capture the non-functional requirements in JIRA as a story?

In a BRD this was pretty straightforward, add the non-functional requirements in its own section and make sure each requirement has a unique ID next to it.

ID: 001 Requirement: The web app shall be compatible with the following browsers: IE11, Firework 50 etc...

But in Agile Scrum, and especially in JIRA, how should these be documented?

Answer 1

Non-functional requirements come in many forms, but they have one thing in common: The don't describe functional behavior of the system but rather put constraints on the design choices that you can make.

Non-functional requirements are ill suited to be expressed as user stories because user stories work best when they can be implemented once in a short timeframe (compared to the length of the entire project) and then be considered Done. After a story is Done, there should be no need to regularly revisit the story. For non-functional requirements, that doesn't work, because adherence to them needs to be maintained over the entire project. You can't say that you will look at browser compatibility only once during the project and ignore it the rest of the time.

For non-functional requirements that affect nearly all (functional) user stories, the best place to document them is as part of the Definition of Done.
For non-functional requirements that affect a relatively small subset of the functionality, you can make them part of the acceptance criteria of the relevant user stories. If this subset is still rather large for your taste (or it might grow in the future and you are afraid that you might miss some non-functional requirement on a future story), you can put the non-functional requirements in a document of some sort and reference that from the acceptance criteria of the relevant stories.

As for the format of the requirements themselves and a possible document to put them in, use whatever works best for you and your team.

Answer 2

"Non-functional requirements" is a bit vague and open to interpretation. Going on your specific example, I would say that those requirements should be used as acceptance criteria for other stories.

If you are concerned about repeating the same non-functional requirements story after story after story, another solution would be to bundle all of these requirements into a document (eg: "application standards"), and make "must adhere to application standards" part of your definition of done.

Answer 3

You can incorporate them into your DOD "Definition Of Done".

Non-functionals are problematic in agile though, if they change you have no way of tracking which stories have been done against what criteria.

So I would try and list them as tests against each story. Even if it meant a lot of copy and paste.

Answer 4

In his book "Essential Scrum", Kenneth S. Rubin says (see p. 93):

I frequently write nonfunctional requirements as user stories […], but I feel no obligation to do so, especially if it seems awkward or more convenient to write them in a different format [i.e. not following the "As a user …" pattern].

That being said, you can simply create a user story in JIRA to document a nonfunctional requirement.

However, Kenneth also recommends—as already pointed out by Ewan and Bart van Ingen Schenau—"[…] that teams try to include as many of the nonfunctional requirements in their definitions of done as they possibly can." This is due to the fact that nonfunctional requirements often affect many other (functional) user stories and if they are not being addressed, the story isn't done. Therefore, the definition of done quite often is the better place.