Software Requirements FAQ and Examples

by J. David Giese on April 27, 2022

Introduction 🔗

The software requirements specification, or SRS, is one of the key documents that needs to be written when writing medical device software. The SRS describes what the software needs to do. At its heart is a list of formal software requirements.

If you contract Innolitics to develop medical device software, one of the first things we’ll do is to write a draft SRS, so we have a lot of experience writing these documents.

When we’re consulting with medical device companies about their FDA submissions, we get asked a lot of questions about writing good requirements. This article provides answers to some of the most frequently asked questions. At the end we also include examples of bad requirements.

If you’re looking to outsource your medical device software development or if you’d like to consult with documentation experts for your device, we’d be happy to help.

Frequently Asked Questions 🔗

How are requirements and design inputs different? 🔗

They’re not. A “design input” is the term that is used in the regulation 21 CFR 820.30, and the corresponding Design Controls Guidance. The term “requirement” is used in IEC 62304 and most other contexts.

How many requirements do we need? 🔗

It’s possible to err by having too few or too many. Here are a few heuristics:

Sometimes, especially if you’re writing requirements for software that’s already been built, it’s easy to write requirements that prescribe a particular design. Good requirements don’t describe the design, rather, they describe the constraints that the design has to fulfill.

Occasionally there may be a business reason why a particular design must be used. In this case, it does make sense to “pin part of the design down” with requirements instead of letting the engineers come up with their own design. However, this should be avoided when possible.

Why is it important that requirements not prescribe a design? 🔗

First, doing so will result in many more requirements than you need, making your verification more expensive. Also, a lot of the verification steps won’t be especially useful since you’ll be checking secondary design choices rather than the fundamental requirements the design had to meet. Second, it will be more costly to update the software if the desired design changes.

For example, you could have a requirement that says:

REQ-1: The software shall use Yocto to generate it’s operating system image.

This requirement could be verified by inspection. This is a bad requirement for a couple of reasons, but for now we’ll focus on the fact that it specifies using a particular tool, Yocto, to generate the operating system image. Why is Yocto specified? Well, probably because we want the system images to be small and for the device to boot quickly. It would be better to replace this requirement with:

REQ-2: The software shall boot in less than 30 seconds.

REQ-3: The operating system image shall be smaller than 200 MB.

These requirements are also easy to verify and their verification will be more useful. REQ-1 could be met, yet REQ-2 and REQ-3 not be met. Also, if you switch away from Yocto to a better tool you’ll need to update REQ-1. If you’d used REQ-2 and REQ-3 you would not need to update your requirements or your verification procedures.

How should requirements be organized? 🔗

The 2022 Draft Software Guidance says:

Format the SRS to be well-organized, easily navigable and readable with the labeling and/or grouping of requirements by function.

We recommend using a hierarchical organization that is implied in the structure of the requirement IDs. E.g., REQ-1.2.3. Thus, you may have this layout:

1 Functional Requirements
1.1 User System
1.1.1 After booting the first time the system will allow for the creation of an admin users.
1.1.2 The admin user shall be able to reset other users’s passwords.
...
2 Performance Requirements
2.1 The software shall boot in under 30 seconds.
...

Only leaf nodes (e.g., 1.1.1, 1.1.2, and 2.1) are requirements. Other nodes are used to organize requirements by type (e.g., 1 and 2) and sub-systems (1.1). As the system grows, you may want to introduce additional levels into the tree.

Why does each requirement need a unique ID? 🔗

The requirements will be listed in documents that are submitted to the FDA. The unique ID is needed so that each requirement can be referred to from various other documents (including, possibly, correspondence with the FDA reviewers). Thus, even if a traceability software could remove the need for these identifiers when you are using that software, the document-centric nature of regulatory submissions necessitates that unique identifiers be assigned at some point.

Furthermore, this means that the unique IDs can not be re-used once a document has been reviewed, approved, and added to document control. This is important because you won’t know if there are other outstanding documents that retain links back to the original ID; if you replaced it with a new ID, it would become unclear whether these links should or should not point to the new requirement.

How big should your requirements be? 🔗

They need to be stated in terms that permit the establishment of test criteria and performance of tests to determine whether the test criteria have been met. Thus, it’s usually convenient to split up the requirements into small statements, each of which has its own unique identifier that can be traced to a verification procedure. There is no regulatory reason why you couldn’t include several statements under a single requirement identifier, but doing so will make verification more error-prone.

For example, if you have one big requirement, say REQ-10, and it has 15 statements within it, how will you know that all 15 statements have been verified? You’ll need to check that your verification procedure covers all 15 of them. If you had split out REQ-10 into REQ-10.1, REQ-10.2, … , REQ-10.15, your traceability table would ensure your verification procedure is comprehensive.

One advantage of big requirements is that it simplifies managing the requirement IDs.

Why is it important to trace software requirements to user needs? 🔗

User needs are general statements of, well, what your users need! Conventionally they are noun-phrases that start with with the word “To”. E.g., “To understand how the device arrived at its recommendation”. Unlike requirements, user needs should be written in language that would be understandable to the user groups they trace back to. User needs are kind of similar to marketing claims in this sense. If you can’t express a user need in language that would make sense to the user group, then it may actually be a requirement. You can get back to the user need by asking “why” this is a requirement. Usually the why question will take you up a level of abstraction so that you can then identify the generic user need that that requirement is meeting.

Tracing user needs to requirements can not only help you identify undocumented requirements, but also undocumented user needs.

As you write requirements, you may realize that some user needs are actually better placed with the requirements. Typically there are more requirements than there are user needs.

Can I use GitHub Issues (or Jira Issues, etc.) as requirements? 🔗

The 2022 Draft Software Guidance says:

FDA acknowledges that modern development practices may employ incremental or evolutionary software development practices. Additional forms of software requirements might be included in the submission, such as well elaborated stories, use cases, textual descriptions, screen mockups, and control flows.

Thus, the FDA is likely okay with you using GitHub issues so long as each one is uniquely identifiable, unambitious, verifiable, and doesn’t contradict other issues. However, we generally recommend against using user stories to track your requirements.

Doing so introduces a few difficulties. First, you would need a mechanism to address changing user stories. If you just use a simple issue tracking system and you close out the issues once they’re complete, then if the requirements in Issue 403 are partially overridden by Issue 892, then what are the correct requirements to include in the next regulatory submission? It can get difficult to keep up with. Issue trackers tend to track changes while the SRS needs to be a complete, unambiguous, and non-contradictory list of the current requirements.

How do user interface mockups relate to software requirements? 🔗

The 2022 Draft Software Guidance says:

FDA acknowledges that modern development practices may employ incremental or evolutionary software development practices. Additional forms of software requirements might be included in the submission, such as well elaborated stories, use cases, textual descriptions, screen mockups, and control flows.

Usually your software won’t look exactly like the user interface mockups. Thus, if mockups are included in your requirements, the corresponding verification procedures will need to indicate how much the software can vary from the mockups.

Sometimes, if the precise design of the mockups isn’t really “required”, it may be better to treat the UI mockups as if they were “design outputs” rather than “design inputs”. Both approaches are valid, and it really depends on whether it’s important to verify that the user interface matches a particular design, or if the particular user interface isn’t so important.

Who should write software requirements? 🔗

This is a hotly debated topic at Innolitics. Often business analysts or project managers will write these. Gathering and document requirements is a different skill than software development and many engineers are not able to and are not interested in learning to do it. On the other hand, since the engineers are often very involved with the design and verification steps, it’s helpful for the engineers to be able to write requirements. On some of our projects the engineers will take loosely specified issues from the project manager and turn them into formal, verifiable requirements stored in the git repository alongside the code. We check for the addition of new requirements in our pull request reviews.

How do you verify that your requirements are correct? 🔗

First, you need to look at each requirement individually. For each requirement, ask these questions:

Second, you need to consider the requirements collectively:

Identifying missing requirements is difficult. Here are some questions to ask to help answer this:

Bad Requirement Examples 🔗

  1. The software shall allow the user to install upgrades, depending on user role. This couldn’t be verified unless one knew which user roles can install upgrades. Thus, it should be rewritten:

    Better: The software shall allow “Admin” and “IT” users to install upgrades.

  2. The software shall support multi-touch gestures on all pages. Unless “multi-touch gestures” is defined more precisely somewhere else in the SRS, this requirement is too vague to verified. What multi-touch gestures need to be supported? What will they do? It needs to be split out into smaller, verifiable, requirements or “multi-touch gestures” needs to be given a precise definition.
  3. The software shall be able to send email messages to users. Without knowing when emails should be sent to users, it’s not clear how you would verify this requirement. This can be solved by making the requirement more specific: “The software shall send emails to the ordering physician when the test completes.”
  4. The software shall be developed to be in compliance with the FDA guidance requirements. The FDA has a lot of guidance documents. Some, such as their “General Principles of Software Validation and Content of Premarket Submissions for Device Software Functions, provide guidance about how the software should be developed. Others, such as the now out-dated 2018 Cybersecurity Guidance, include requirements that the software must fulfill, e.g., a user login system, encryption in transit, etc. The former guidance documents should not be listed as requirements because they don’t define what the software itself must do. The latter guidance documents may be valid.

    Even if we assume this requirement, as written, only includes the latter group of guidance, it’s still too big and vague to verify. It should probably be removed or turned into a user need with several specific requirements tracing back to it from the various relevant guidance documents.

  5. The software shall be developed in compliance with FDA 21 CFR 820.30. This is not a valid requirement because 21 CFR 820.30, or the design controls regulation, applies to the design process that was used to develop the software. Thus, it is not really a requirement of the software itself.
  6. The software shall include a Patient Home Page. This requirement is unnecessary. There are almost certainly other requirements that indicate that functionality will be present on the Patient Home Page. For example, “The Patient Home Page shall list all of the tests the patient has completed.” This requirement implies that the Patient Home Page exists.
  7. The header bar shall show the user’s email address and username when they hover over their profile picture. It depends on additional context, but this requirement does not seem very important. If there’s no verification test for this feature and somehow it breaks, it’s probably fine. Furthermore, it’s the sort of feature that’s unlikely to break. Thus, it can probably be removed.

    Not every aspect of the software’s functionality can or should be listed as requirements. To do this would require, more or less, that you write an SRS that is as detailed as the source code itself. Thus, requirements should be reserved for things that need to be verified.

  8. 1. On the test history table, each test can be editable, by clicking on the ‘edit’ icon. 2. Once a test is edited, there shall be options to ‘save’ the entry and ‘close’ the window. These two requirements are likely too specific and may constraint the designs available to the engineers implementing the requirements. Furthermore, if the design changes, the requirements will also need to change. It would likely be better to combine these into a single requirement that says: “The Test History Table shall provide a mechanism to edit each test in it.” It would also be good to clarify what it means for the results to be editable.

Get Medtech Software Tips

Subscribe using RSS

How frequently are they sent?

We send out tips about once a month.

What will I read?

Articles about software development, AI, signal and image processing, medical regulations, and other topics of interest to professionals in the medical device software industry.

You may view previous articles here.

Who creates the content?

The Innolitics team, and experts we collaborate with, write all of our articles.

Want to know more?

Contact us.