Before we get started: I also uploaded a free template for a software requirements list - have a look!
What the Hell are Software Requirements?
Software Requirements are what, um, professionals write down to describe their software before they start coding. Wait, what? People step away from the computer and write down stuff before getting to work? Yep.
You could attempt to compare software development with architecture: Before you start building a house, you should have an idea of how that house should look like. You should have a plan.
Unfortunately, most software development isn’t done this way. Why? I don’t know. Maybe software development is inherently more complex than constructing buildings. But is that true? At least the solution space is larger: In a building there are only so many ways to transport water (pipes). In software, a seemingly simple task (sending data to a frontend) can be accomplished in a multitude of ways which are hardly similar.
But let’s not go there today. There’s not much point in arguing with regulatory requirements anyway.
I’ve spent considerable time writing software requirements and even attempted to read a book on it. The summary is: There isn’t an objectively correct, universally-accepted way to write them.
Let’s see what we can do about that.
Writing Software Requirements for IEC 62304
If I’d just tell you “write a document and describe what your software does”, what would you do? Probably not much.
Instead, I could ask you: “What do you tell your developers when you come up with a new feature? How do you communicate its behavior so that they know what to build?”. Then you would probably shrug and say you just send them a message an Slack or shout across the room. I can’t blame you. That’s how software is being developed nowadays.
The IEC 62304 however requires a more formal approach. You need to document whatever you want to develop. Generally speaking, this makes sense: How else could an auditor understand what your software does without actually executing it or looking at the code?
So: You need a list of software requirements. How does a software requirement look, anyway? The way I see it, there are two ways to write them: User Stories and what I call “Feature Descriptions”.
Option 1: User Stories
Many companies already base their development on User Stories with varying degrees of success. The idea is to describe whatever you want to build from a user’s perspective. For example, the German Covid-19 tracking app (“Corona-Warn”) has some pretty good documentation based on User Stories.
User stories for such a tracking app could look like this:
- As an app user, the first time I launch the app, I want to receive an introduction to how it works.
- As an app user, I want the app to be displayed in my language the first time I use it, so that I can understand how to use the app.
Those make a lot of sense and work reasonably well. However, User Stories almost always include a trade-off - they sacrifice detailedness in favor of the user’s perspective? Um, what?
In the first User Story above, there’s no description what happens on subsequent launches. The introduction won’t be shown - but what will be shown instead? More questions: Can the user “reset” the app and will this re-display the introduction screen on next launch? Can the user customize whichever screen is shown at the beginning?
Second story. What happens if the language of the user is not available? Will the app quit? Or will it default to English? Can the user select the app language manually?
These may sound like nitpicks - and I agree! If you spec things out on this detail level, you probably won’t ship before humans start colonizing Mars. But they illustrate the shortcomings of User Stories.
Then there are other “non-user requirements” which just don’t fit into the User Story format:
- As an app user, I want my password to be hashed so that hackers can’t read it and log into my Twitter account and look at cat pictures.
- As an app user, I want the app to have reasonable CPU usage so that my phone doesn’t explode.
These are quite technical requirements. The average user doesn’t care about them! But they’re still important. It sounds rather clunky to phrase them as User Stories. Which brings us to our next option, “Feature Descriptions”.
Option 2: “Feature Descriptions”
Feature Descriptions are User Stories without the boilerplate. I like to refer to them as “User Stories for grown-ups”. Applying those to the examples above, here’s how they would look. There’s a headline with some explanatory bullet points underneath.
1. On first launch, show introduction
- On subsequent launches, show dashboard
- When app is reset in settings, show the introduction on next launch again
2. Select language locale based on user settings in operating system
- If user locale doesn’t exist in app, default to English
3. Save passwords as hashed passwords to database
- Use secure hashing algorithm with salt, e.g. bcrypt
4. Long-term CPU usage should be below 2%
- (No further explanation needed)
Notice how these are less ambiguous and allow you to go deeper into specific behavior / edge cases? Also, not having to view everything from the user’s standpoint can be liberating as many requirements are technical in nature.
Compared to User Stories, you gain succinctness and a higher level of detail. But you sacrifice the user’s perspective which may sometime force you to re-consider a feature which may not yield much value to your users. It’s a trade-off. And it’s your decision to make.
Additional Software Requirements Content
So you’re done, right? Sorry, not quite. Here’s where additional regulatory work begins. You have to:
- Categorize each software requirement based on the 62304 categories (we’ll learn more about those shortly)
- Determine whether risks are associated with each software requirement
- Label software requirements which are risk control measures (we’ll also learn about those)
- Ensure traceability.
Great. Sounds like a ton of work? It’s not too bad. But enough to ensure that consultants like me can make a living.
62304 Categories
The IEC 62304:2006 lists a number of software requirement categories. It makes a lot of sense for you to use those as this enables you to somewhat prove that your requirements are complete.
These include (there are a few more):
- Functional requirements
- Inputs and outputs, interfaces
- Security requirements
- User interface requirements
- Data definition and database requirements
- Regulatory requirements
It’s pretty straightforward. Going back to our examples above, you could argue that 1. and 4. are functional requirements while 2. is a user interface requirement and 3. is a security requirement.
By the way: You could (and should) include UI mock-ups (images) as part of your user interface requirements. With those, you also cover some requirements of the IEC 62366.
Determine Associated Risks
Next, you determine whether risks are associated with your software requirement.
Let’s look at our examples. Maybe if there’s a bug in 2. (default language displayed is English), the wrong language could be displayed and the software becomes unusable to the user?
For each software requirement, you have to consider if something like that could exist. You’ll do the more in-depth risk analysis elsewhere based on the ISO 14971 (fun!), hopefully I’ll have an article on that soon.
Label Requirements Which Are Risk Control Measures
Some of your risks may need additional risk control measures. Without going into too much detail here, we could say that 4. (hash passwords) is a risk control measure.
The scenario is as follows: In your risk analysis, you determined that a data breach would pose a significant risk to your users because their login data would get leaked which would lead to everyone’s twitter accounts being hacked because they’ve been using the same password everywhere. You want to reduce that risk by storing passwords not as plain text, but as hashes - great idea! That’s why you write down a software requirement (4.) which specifies that. That software requirement is a so-called risk control measure.
This is a simple yes / no label for each software requirement.
Ensure Traceability
Traceability is any auditor’s favorite buzzword. It’s about how you ensure that you’ve implemented all your software requirements, that you’ve tested all of them and that related risks were actually analyzed. Let’s see how a simple implementation of this could look:
- You use GitHub and implement code in pull requests. Each software requirement has a list of pull request IDs in which it is implemented. That enables you to prove that 1) each software requirement was actually implemented and 2) which code was changed or added because of it.
- You do some manual QA testing in which someone performs actions on a staging deployment of your software. In your protocol for that, you have at least one test associated with each software requirement ID. With that, you can prove that each software requirement has been tested. Of course, you could also do automated tests, you just need some way to associate a test with a software requirement ID.
- Each software requirement has an ID. If a software requirements has an associated risk, the risk IDs are listed next to the software requirement.
So you can think about it like relations in a relational database. Only in this case, your “database” is a spreadsheet and it has no foreign key constraints whatsoever. Welcome to regulatory work!
Putting It All Together
A sample software requirement list could look like this. I’ve also added a column “Software System” so that you can separate backend from frontend (app) requirements. I also shortened the descriptions to not destroy my page layout.
I’ve also uploaded a free template of this for you :)
| ID | Software System | Category | Description | Risk Control Measure? | Related Risk IDs |
|---|---|---|---|---|---|
| 1 | App | Functional | On first launch, show introduction | No | |
| 2 | App | User Interface | Use user locale (language) | No | 1 (Risk ID) |
| 3 | Backend | Security | Store passwords as hashes | Yes | |
| 4 | App | Functional | Average CPU usage < 2% | No |
And then of course you’d have a separate risk table and software system test table, both of which reference software requirements by ID in their rows. The spreadsheet chaos begins!
Using a Tool
You could also use a tool for this, like Jira or GitHub Issues. It’s usually quite some work to get it set up properly, especially to ensure traceability (see above). I haven’t seen any great implementations of this so far. But it can certainly be worth it if you can avoid spreadsheet hell.
Conclusion: It’s a Mess
Defining software requirements makes a lot of sense. It forces you to think about what you want to build before diving into code.
But the regulatory requirements, especially traceability, are tricky to fulfil as there aren’t any great tools out there. I’ll hopefully build one in the future.
For now, your best bet is a bunch of spreadsheets. Feel free to use my template as a starting point. Even if you decide to migrate to a separate tool later on, your content should be the same.