Requirements Gathering (WIP)

Purpose

Requirements gathering is the process of figuring out what we should build. It’s about finding product-market fit. Elegant, fully-tested, fully-documented software is useless if nobody wants to use it!

Requirements gathering is hard. Our startup clients may not know exactly who their users are or what they want. If they don’t know, then how can we help? There are a few ways:

Although these are all good ways to help, requirements gathering is a joint activity between us engineers and the product owner. We don’t have the full business or clinical picture. This is one of the reasons why weekly progress demos and sprint planning meetings are helpful—they give our clients an opportunity to refine the requirements iteratively.

If we want to accelerate progress in the medical device industry, we need to build devices that are useful. If you want to work on devices that help patients, you should care about requirements gathering.

In this lesson we’ll discuss some best practices requirements gathering in general, as well aspects of requirements gathering that are specific to medical devices.

The Why-Spectrum

In a sense, requirements gathering is about asking “why”.

This is usually as far as we go, but we could go further:

If we keep asking why we’ll bottom out.

At each level there could be other answers: We may use dcmtk for other purposes too. Also, it doesn’t answer why we used dcmtk in particular. At a higher level, the radiologist may want to finish their work to make money or get home to their family. Therefore, the sequence of why-questions is better thought of as directed-acyclic graph than a tree with the “good” at its root.

There is a spectrum that we step up with each subsequent “why”. When we document requirements for medical devices, we divide this spectrum into different requirements levels. A simple software-only medical device may have three levels:

Level Example
design specifications (the FDA calls these “design outputs”) how we’re building the device
requirements (the FDA calls these “design inputs”) what we’re building
user needs why we’re building the device

Note that the term “requirement” can refer to all levels (as in the term requirements gathering) as well as for it’s particular level between user needs and design specifications.

It’s occasionally not clear whether a statement is a user need or a requirement. That this would occur is apparent once one recognizes that user needs and requirements lie on a spectrum. User needs are higher level and more abstract or fluffy. Try to use consistent levels of abstraction (just like you do in your code).

The goal of documenting requirements is to help us make devices safer and more effective. Overly-detailed documentation can be too complicated to be useful. (It’s like 5000-line function—you can’t keep it all in your head!) If you start to have a lot of requirements at a particular level, you may want to introduce additional levels. For example, on a larger software-and-hardware medical device we may have more levels:

Level Example
detailed design specifications a docstring for a function
design specifications a project-level architectural diagram
software item requirements granular statements about what a software component must do
software requirements more abstract statements about a software system
system requirements statements about what the whole device (including non-software) must do
user needs more abstract statements about what users want

Discovery Phase

We usually start projects with a discovery phase that does the bulk of requirements gathering and provides a cost estimate to clients. Although we like agile processes, we still believe it makes sense to do a lot of requirements gathering at the beginning of projects. Hopefully most of the user needs and requirements remain fixed through out the project.

User Groups

It’s helpful to start by identify your different user groups. Different groups often have different, and possibly conflicting, needs. Writing out the groups, and possibly also their use cases and personas, can help identify their associate user needs. Similarly, knowing the user needs can help identify new requirements.

The ways in which users differ from one another are unlimited, so you should focus on user characteristics that could have a particular influence on what they need from the device, such as age, education or literacy level, sensory or physical impairments or occupational specialty.

User groups often correspond with different market segments. E.g., one of the devices we’ve worked on is used by ENTs and pediatrician. Each group had different needs and are also marketed to differently.

User Needs

TODO: fill this in

Requirements

TODO: fill this in

TODO: address these

Traceability Tables

Tracing design specifications to requirements to user needs can identify gaps. E.g., you may have a user need that isn’t being met by any requirements. You may also have some requirements that don’t map to a documented user need, thus pointing to an implicit user need you hadn’t identified previously. Medical device submissions require us to document this, usually in a traceability table.

Learning Material

Read chapters I through IV of book I of Nicomachean Ethics. Here is a pretty good translations.

Read through this tweet sequence.

Watch this short video on design controls (here are the slides and a transcript).

Read the Introduction, Section C on Design inputs, and Section D on Design outputs of the FDA’s Design Control Guidance For Medical Device Manufacturers.

Exercises

To learn as much as possible from these exercises, write your responses before revealing the provided answers. If any exercises seem irrelevant, you can skip them and instead write a justification as to why they are unimportant. These justifications will help us improve the lesson for future students.

Exercise 1

What is the difference between user needs and design inputs?

Exercise 2

What is the difference between a design input and a requirement?

Exercise 3

What is the difference between a design input and a design output?

Exercise 4

How does the FDA use the the term specification?

Exercise 5

Do you think engineers should be involved with requirements gathering? If so, why?

Exercise 6

Select one of our internal projects (e.g., RDM or the DICOM Standard Browser). Using Notion, create a table with all of the relevant user groups. Write out brief user personas for each group. Then create a table and write out user needs and trace them back to the user groups (using a relation column). Finally create a table with software requirements and write some of these. Trace them back to the user needs. There’s no need to be comprehensive.

Exercise 7

You are developing a web application that consists of multiple modules. These modules are largely independent, but they currently utilize the same JavaScript bundle. An issue to split the bundle for better performance was created several months ago. This issue has not been prioritized. The client suddenly prioritizes the issue. How do you respond?

Answer

This situation occurred during a real project. The client was actually concerned with an external dependency that had caused a short downtime when the dependency’s server was not available. Splitting the bundle would not have prevented this problem, but it is easy to understand the client’s confusion since the issue described limiting the loading of dependencies.

Fortunately, the engineer had noticed the downtime, and he suspected the sudden shift in the issue’s priority might be related. He confirmed with the client that this dependency issue should be addressed and included a fix.

Unfortunately, the engineer also chose to continue implementing the bundle-splitting logic as specified in the issue without reconfirming the client’s desire to pursue the issue’s stated change. After spending nearly two days updating configuration, the engineer demonstrated the reduced bundle sizes to the client only to realize that the client had already been satisfied with the application’s original loading speed!

The engineer could have avoided days of unnecessary work at a cost of perhaps half an hour of requirements gathering. Clarifying the requirements and reducing the issue scope accordingly would also have illustrated Innolitics’ role as a venture partner rather than a service provider attempting to maximize billable hours.

Continuous Lesson Improvement

Please help us make these lessons as relevant and up-to-date for future engineers as possible!

You can help in several ways:

  • Shorten or clarify the writing. We're all busy and less is more.
  • Ask if the purpose of the lesson is unclear. We want all of the lessons to seem useful.
  • Remove exercises or learning material that aren't useful.
  • Add more exercises, exercise answers, or learning material as appropriate.

You can quickly open the lesson page in the GitHub editor. Create a new branch and pull request and assign it to David.