Crafting Good Requirements for Medical Device Software

To develop software, we need clear requirements. Too often, software projects struggle because the requirements are poorly written. Instead of being given clear directions, the developers are handed nothing more than a picture with a bunch of notes. In these situations, developers have more questions than answers, and all of the people involved in the project – the client, the BAs, designers and testers, etc. – lack an understanding of the reason for the product and the problem it is trying to solve for users. For Software as a Medical Device (SaMD), DTx and connected medical device systems, understanding the software system as a whole, and who will use it, is crucial to mitigating use errors. With good requirements, the development team can spot missed edge cases and close gaps during the formal story requirements review (we call this “baking”).

In the medical device software space, requirements need to not just be “good” but also verifiable, testable and traceable up to user needs. These processes and the Agile development process in general benefit from well-written requirements 

As a UX and Human Factors expert, I have worked on software development projects that have employed Use Cases and Functional Specifications, but these never seem to convey all of the necessary information. They tend to be verbose, and are not fun to write, read or manage. A good requirement should tell each audience member exactly what the expected functionality is without generating a myriad of questions or raising the eyebrows of all involved. Here’s what comprises good requirements.

Good Requirements Have:

• User Story Phrase
• Story Detail Requirements
• User Acceptance Tests
• Workflows
• Wireframes

Each element brings a lot to the table, but too often they are judged as a “waste of time.” Yet without any one of these elements, the requirements start to lose value. Contrary to being a waste of time, when you have all of these elements in your requirements, you create a synergy that speeds up the development process.

Let’s look at each element in detail. 

User Story Phrase

This states the scenario of the users involved. Story phrases should read:

As a SOME ROLE,

I want to DO SOMETHING,

So that I CAN GET SOME BENEFIT.

The user story phrases are critical to lay out exactly who is going to do what, and for what reason(s). Often the first outline of requirements is a list of user story phrases t. These phrases serve the critical role of defining scope as well as linking each requirement to the persona it affects. In the medical device software space, it’s important to note there may be different types of patient and clinical personas as well as other supporting personas.

Story Detail Requirements

These are the details of the feature. It’s important to document the screen elements such as fields, labels, validation criteria, messages, actions, buttons and error states. This is essentially the functional specification of the details of the screen(s) involved. Because it’s in the context of the wireframe (more on that later), it’s more concise. You can simply reference the field name rather than verbosely state everything about it.

In the medical device software space, story details can include things like relevant device timeouts, whether a therapy is happening at the time and whether or not multiple devices could be present.

User Acceptance Tests

User acceptance tests should include all scenarios relevant to the user story phrase. These should not be too detailed – they don’t need to mention specific screens or a complete list of actions to execute the steps, for instance. As an example:

GIVEN that condition 1 and condition 2….

WHEN I do step 1, and step 2…

THEN, desired result 1, desired result 2….

User acceptance tests define a set of tests that all involved can walk through to understand how the feature will work. A real tester could navigate these actual scenarios word-for-word to confirm that a feature is complete and working. 

In the medical device software space, it’s important to remember that each requirement be verifiable. User acceptance tests are the foundation for the verification protocols that serve to validate the product.

Workflows

Workflows should include a picture of the screens involved and how they logically fit together. The workflow picture is worth a thousand words, as the details of the flow through the feature can be quite complex. Our favorite tool for workflows is Figma. The app screens already reside there, and we can easily add arrows and logical elements to convey a flow. In some cases, such as when the logic of the workflow is particularly heavy, we will instead use Lucidchart. When making workflows, error states should be documented. 

Workflows are particularly important in the medical device software space because they lay the foundation for creating wireframes. Just as a floor plan describes the flow through a building, workflows describe the flow through the software that the wireframes will need to support.

Wireframes

A wireframe is required for each screen involved in the design. Although initial ideation wireframes may be low-fidelity or even hand sketched, wireframes for requirements should be medium to high-fidelity. For example, it’s ideal to include high-fidelity screens with the user stories when using Figma, since they reside in the same program. This can be accomplished by exporting each screen as a PNG and embedding it in a Confluence page or whatever tool you are using to house the requirements. 

It is important to include all error screens and edge case screens in your wireframes. For medical device software, the scenarios these screens comprise are essential to the verification protocols.

Achieving a Smooth Project

If each Agile sprint begins with all its features fully documented in the formats described above, it runs smoothly and often finishes early, leaving time for those to-do’s that we all keep on a running list. Writing requirements in this format helps clarify the development team’s questions for the client. Detailed workflow and acceptance tests are good methods to gauge the completeness of the requirements. This is especially useful for medical device software, SaMD and DTx, where achieving clarity around what is a properly functioning application is a regulatory requirement and prevents accidental harm to the health of patients.

About the Author

Bob Moll directs user experience and human factors initiatives for Orthogonal’s SaMD projects. He oversees user definition, use environment analysis, user workflow modeling, and interface design and development for FDA in an agile environment. Over the past two decades, Bob has worked with a range of enterprises, from Fortune 500 companies to innovative startups, designing successful new products from scratch and reenergizing existing products with improved user experiences. Bob has served clients and a wide range of their users in the financial services, education, and medical design spaces.