Note: this is only an introduction to medical device software documentation. Experienced readers will see that I’ve left out (intentionally) many details about the documentation needed for medical device software.
An Awkward Couple
There is a basic mismatch between modern software development methods and medical device regulatory compliance documentation. Anyone familiar with agile methods for software development knows that agile emphasizes working software over documentation and that eliminating unnecessary documentation helps agile teams be more productive and flexible. Right?
But in the highly regulated world of medical devices, there is a lot of necessary documentation. Therefore the goal for agile teams developing medical software is not to eliminate documentation but to be as efficient as possible in generating and updating the software documentation. Another way to think about this is that the “definition of done” for a software team is not just finished software, it’s also delivering completed software documentation.
Many people misunderstand the purpose of documentation in medical device regulatory compliance. They often think the documents only refer to the design of the product but in fact the regulations are focused on processes and the documents are the evidence that your team is following the processes. So if you’re only documenting the design then you’re missing the majority of the documentation needed for compliance.
For example, here are the parts of the software development process defined in the IEC 62304 medical software standard with corresponding documents (evidence) for each process (activity).
|62304 Processes (Activities)||Examples of Evidence|
|5.1 SW Development Planning|
planning the goals of the SW development project, the tasks and deliverables, roles and responsibilities; coordinating across groups; allocating resources; and controlling risks
|Software Development Plan (or Design & Development Plan)|
|5.2 SW Requirements Analysis|
decomposing system/product requirements into SW requirements within the context of the system architecture design (identifying the system functions that are to be implemented in software)
|Software Requirements Specification|
|5.3 SW Architectural Design|
high level design of the software, including partitioning/segregation of high-risk software, as appropriate, and interfaces
|Software Architectural Design (or System Architectural Design)|
|5.4 SW Detailed Design|
defining the software units and their interfaces, including state diagrams, data structures, and risk controls
|Software Design Specification (or Software Detailed Design or Software Specification)|
|5.5 SW Unit Implementation & Verification|
the core of software development; coding and testing; code reviews; static analysis
|Software Unit Verification Summary (or Code Unit Verification)|
|5.6 SW Integration & Integration Testing|
merge software units and demonstrate that multiple software components work properly together and with the system hardware
|Software Unit Verification Summary (or Software Test Report)|
|5.7 SW System Testing|
verification of software against the software requirements in a system environment
|Software Test Protocols and Test Reports|
|5.8 SW Release|
deploying a controlled, verified version of software
|Release Notes, Revision History, Open Bug List, SBOM, etc.|
Knowledge Is Power
Make sure everyone on the software team knows what needs to be documented, when documents need to be released, and how software changes impact the documentation. With this basic knowledge the team can make intelligent tradeoffs in planning their work and make accurate estimates for completing tasks (and not run into unpleasant surprises at the time of software release).
This information should be clearly described in your company’s quality system SOPs (and to a lesser extent in each project’s Software Development Plan) and everyone involved should be trained on the procedures. The goal here is to integrate the documentation work into your software development methods so it becomes a matter of “turning the crank” instead of wasting time in lots of meetings and emails trying to figure out what needs to be documented.
Example Set of Software Documents
The table below describes a typical set of documents for medical device software (assumes Safety Classification = B). Note that there are many different ways to structure your software documentation and still comply with the IEC 62304 standard and FDA software guidances; this is just one way. For example, some companies use the title “Software Design Specification” or “Software Specification” instead of “Software Detailed Design.”
|Software Development Plan (SDP)||Defines SW development activities, roles/responsibilities, deliverables, and SW testing for this SW project. Serves as the master document for the SW project. Establishes overall risk level of software–defines A/B/C class (per 62304) and Level of Concern (per FDA)|
|System Hazard Analysis (SHA)||Top-down risk analysis which includes analysis of effects of potential SW failures and where SW serves as a risk control (alternative: analyze SW failures in specific SW DFMEA and cybersecurity risk analysis documents|
|Software Requirements Specification (SRS)||Defines what the SW needs to do; forms basis for SW system-level testing; implements product requirements; implements risk control measures|
|Software Architectural Design (SWAD)||High-level description of software system design, showing which parts are controlled by SW; shows organization of SW (functional units, state diagrams, interfaces, etc.)|
|Software Detailed Design (SDD)||Detailed description of SW design (how the SW reqts are implemented); includes UI design; written at a level that a SW engineer could understand the design and make changes for software upgrades|
|Software Test Plan (STP)||Defines how software will be tested (all types of software testing); roles/responsibilities, resources needed for testing; key milestones and phases; can be combined with the overall SDP|
|Software Design Review records||Meeting minutes, decisions/conclusions, action items, and data reviewed at key milestones in the SW project|
|Software Unit Verification Summary||Evidence of unit testing, code reviews, and static analysis|
|Software Verification Protocols||Documents defining test methods, acceptance criteria, and test environments for testing of SW requirements (typically a set of test cases)|
|Software Traceability Matrix||A cross-reference table that defines traceability between SW requirements, implementation, and SW testing; sometimes combined in the SW V&V Summary Report|
|Software V&V Summary Report||A single report with results of all testing of SW requirements and overall product validation|
|Unresolved Anomalies Report||Open bug list at time of release with a risk assessment for each bug (can be combined with V&V Summary Report)|
|Software Release Package||Identifies the software being released: SW version, SBOM including all SOUP used in the product; revision level history with table of all SW versions previously released and changes between them; references all documentation associated with this release (the ‘last’ software document)|
|Software Maintenance Plan||Describes how the software (including SOUP) will be monitored throughout its lifetime and updated as needed; may be combined with an overall post-market surveillance plan or simply be covered by QMS procedures|
|Validation for software test tools / test scripts||Sets of validation documentation (plans, designs, test protocols/reports, etc.) to qualify SW tools used in V&V testing|
That’s a long list of documents and every time the team makes a change to the software they need to update some or all of the software documentation. Think about the impact of that on your software team–it can easily take longer to update all the documentation than to update the software! What to do?
This is where automatic generation of documentation from software tools makes a huge difference. First consider the documents that are most frequently affected by changes to the software: requirements, design, test, and trace documents. Then look at the information already stored and managed in the team’s development tools and develop ways to extract that information into the formal compliance documentation. For example, you can export a set of test cases from a test management tool and turn them into a formal software test protocol document, signed off in Doc Control.
In my experience, once a software team has gone through the laborious process of creating all the documentation by hand, they can be very resourceful in figuring out ways to automatically generate document content. Investing time up front on this kind of automation will save time on every subsequent software release.
The documentation needed for medical device software is lengthy and complex. Make sure everyone on the software team knows what documentation is needed and integrate that into the development workflow. And try to leverage software tools as much as possible to automatically generate document content.
Here’s an alternative set of example software documents from Promenade Software:
Here are even more documents: this is a map of medical device documentation showing relationships of software, hardware, and product DHF documentation and the content of a 510(k) submission: Medical Device Documentation Map
Author’s note: The FDA released new guidance in 2023 that changes what they expect in a software submission. For example, they no longer use Level of Concern. The table below has been updated to compare the requirements of the old (2005) guidance with the new (2023) guidance.
This table, copied from the FDA software guidance on premarket submissions, summarizes the basic software documentation FDA expects in a regulatory submission. The required documentation depends on the safety risk of the software: categorized as either Basic or Enhanced. The table marks the additional documentation for Enhanced level with an asterisk (*). Note that separate documentation for cybersecurity, usability, and other aspects of the product required for FDA submissions are not shown here. For a description of required cybersecurity documentation, click here: Getting Started with the New FDA Cybersecurity Guidance.
|#||Old FDA guidance (2005)||New FDA guidance (2023)||Explanation of FDA documentation element|
|1||Level of Concern||Documentation Level Evaluation||A determination of the software documentation level: Basic or Enhanced, with rationale per FDA criteria. If it is Enhanced then additional documentation needs to be included in the software submission.|
|2||Software Description||Software Description||A summary of what the software does (significant software features, functions, analyses, inputs, and outputs) and its operating environment (e.g. hardware platform or cloud infrastructure)|
|3||Device Hazard Analysis||Risk Management File||Risk Management Plan, risk assessments, risk controls, and Risk Management Report|
|4||Software Requirements Specification (SRS)||Software Requirements Specification (SRS)||Defines what the software needs to do as a set of requirements; design input document that drives software development and forms the basis for software system-level testing.|
|5||Architecture Design Chart||System and Software Architecture Design||Detailed diagrams of the software modules, layers, and interfaces that comprise the system, their relationships, the data inputs/outputs and flow of data, and how users or external products interact with the system and software.|
|6||Software Design Specification (SDS)||Software Design Specification (SDS)||(*) Detailed description of software design: technical design details of how the software functions and how the software requirements are implemented, especially around safety features and UI design|
|7||Traceability Analysis||—||(no longer required as a standalone document; traceability expected to be included in SDS and other documents)|
|8||Software Development Environment Description||Software Development, Configuration Management, and Maintenance Practices||Summary of software life cycle development plan, including a summary of the configuration management and maintenance activities (software development process). |
(*) + Complete configuration management and maintenance plans.
|9||Verification and Validation Documentation||Software Testing as Part of Verification and Validation||A summary description of the software testing activities at the unit, integration, and system levels; system level test protocol including expected results, observed results, pass/fail determination, and system level test report. |
(*) + unit and integration level test protocols including expected results, observed results, pass/fail determination, and unit and integration level test reports.
|10||Revision Level History||Software Version History||A table of tested software versions including the date, version number, and a brief description of all changes relative to the previously tested software version|
|11||Unresolved Anomalies (Bugs or Defects)||Unresolved Software Anomalies||Open bug list at the time of release with a risk assessment for each bug|
|(*) = only required for Enhanced level of documentation|