Tips to Produce a Lean and Useful IEC 62304 Software Architecture Document
By Michael Kahn, Director, Electrical and Firmware Engineering
Capture of software architecture information is one area where developers frequently struggle. Without good practices in place, the task can become a huge time sink without proportionately positive impact on increasing design quality, ensuring device safety, and enabling concurrent activities across different practice areas. Moreover, unwieldy documentation – without necessary or clear content – is less frequently referenced to guide detailed design and verification plan development. Unclear information organization can also add unnecessary overhead to Design History File (DHF) updates when design changes are needed.
Like many companies developing FDA classified medical devices with software, Product Creation Studio has adopted the international standard IEC 62304:2015, “Medical device software – Software life cycle processes,” to ensure compliance as part of our ISO 13485:2016-compliant product development system, PCS+.
When our engineering team is developing the required DHF deliverables within this framework, it is important to have operational practices in place to guide the efficient creation of design documentation. This ensures the desired outcome of the IEC 62304:2015 development process and high design quality and device safety, while at the same time maintaining the high-efficiency required by our organization’s aggressive product development schedules.
Product Creation Studio projects can go from concept to verification prototype devices in four-to-six months, producing equivalent deliverables that may take a year or more when conducted by an OEM (Original Equipment Manufacturer).
Here are some key operational practices we use that can help your development team produce lean, efficient, useful, and maintainable architecture documents to better support aggressive product development schedules.
1. Start Early
Like many ISO 13485:2016 compliant development organizations, Product Creation Studio uses a defined project phase development process to schedule, coordinate, and align concurrent activities and deliverables across multiple practice areas. In our phased project development process, software development team deliverables are rarely in the critical path during pre-architecture project phases.
An effective software developer will use this available time ahead of architecture due dates to identify areas where there are high levels of design complexity, implementation risk, or where the best implementation approach for an architectural element is difficult to determine.
Using this available time to explore and test solutions for critical design elements though rapid prototyping and analysis allows you to enter architecture phase with verified solutions. This decreases the chance of more costly changes downstream in the product development cycle where there are cross-disciplinary dependencies and higher cost of changes.
2. Plan and strategically select level of abstraction and partitioning
Before diving into content creation, capture a detailed outline that includes the decomposition of requirements into “SOFTWARE ITEMS.” Decomposition at the appropriate level of abstraction is a key step for ensuring a useful and maintainable architecture document.
IEC 62304:2015 provides minimal guidance on specific content and leaves it up the “MANUFACTURER” (or you, the manufacture’s assigned developer) to determine the level of abstraction and breakout of “SOFTWARE ITEMS” is appropriate, primarily based on the software risk. The overview of IEC 62304:2015 required process for architecture development is quite brief:
1. Identify software structure and identify SOFTWARE ITEMS [Class B, C]
2. Define SOFTWARE ITEM interfaces [Class B, C]
3. Specify the functional and performance requirements of a SOUP* item [Class B, C]
4. Specify hardware and software requirements for SOUP* item [Class B, C]
5. Identify segregation required for risk control. [Class C]
(*SOUP is Software of Unknown Provenance, or software developed outside an IEC 62304:2015 compliant process)
The key elements and decomposition from software requirements to architecture will be specific to your device. There is rarely a one-size-fits-all template that provides all the help you need to create a useful document.
So, what do we do with this? Let’s try to break it down to some steps and things to consider that might be helpful:
Step 1: Review and fully assimilate design inputs.
Key inputs are the Software Requirements and the Risk Analysis. Your architecture document will always be implemented to meet the requirements and the hazard mitigations included in the requirements document. However, separate review and assimilation of the Risk Analysis and mitigations is important to understand all areas where software plays a role in mitigation of hazards to assure that mitigation functionally is properly addressed in the architecture for appropriate level of reliability and visibility.
Step 2: Select the highest level of abstraction and partitioning possible that is still useful when defining SOFTWARE ITEMS.
Do not confuse “SOFTWARE ITEMS” with “SOFTWARE UNITS”. The IEC 62304:2015 definition of a software items is “any identifiable part of a computer program, i.e., source code, object code, control code, control data, or a collection of these items” versus an IEC 62304:2015 “SOFTWARE UNIT,” defined as “The lowest level that is not further decomposed.” SOFTWARE UNITS are developed later as part of the detailed design phase. As part of the architecture definition, you will be defining SOFTWARE ITEMS.
Here are some questions to ask when evaluating the appropriate level of abstraction for decomposing software requirements to define SOFTWARE ITEMS:
a. Is the software system partitioned to allow independent, concurrent development of more than one software developer in addition to supporting and informing hardware development?
b. Are these independently verifiable blocks optimized to support integration testing? Can the architecture document be used to develop the software integration verification/test plan (not protocol)?
c. Does the level of abstraction enforce the needed level segregation or visibility to crucial outputs to support risk mitigation and software hazard analysis?
Step 3: Efficiently handle SOUP (Software of Unknown Provenance) or off-the-shelf software
For runtime libraries, logically group SOUP where resource requirements and performance requirements can be specified as a group.
Functional and performance requirements for peripheral APIs and their system resources needed to operate typically must be individually specified but specify the subset of functionally required where applicable.
Make sure that version control of SOUP you bring into the project is properly accounted for in the software development plan along with specific guidance of how new versions can be integrated and verified.
From the steps above, organize the document outline into a structure that makes sense for this design and capture a backlog of manageable sub-tasks to complete.
3. Go “Agile”
The Agile development process has the advantage of prioritizing and breaking execution into manageable, executable chunks within a fixed time period. The overall time from draft to release is significantly shortened by interleaving design review and update cycles, systematic review and re-prioritizing of content backlog, and maintaining focus on tasks to complete. When executed effectively, the overall time to release is both reduced and more deterministic. In addition, the overall quality is improved with regular review of manageable subsets.
Figure 1: Sequential vs. Agile development
Consider two different approaches for the equivalent scope of work. The Agile workflow saves up to 20% of the effort on the initial draft by both maintaining focus and re-planning, and re-prioritization at the start of every new sprint. The possibility of a lengthy review cycle at the first internal release is eliminated, along with reducing the chance of a lengthy design update cycle.
4. Resist the tendency to put detailed design content in your architecture document.
It is common for developers to work on aspects of the design detail while capturing the software architecture. This detail can inform and validate the architecture approach, but resist capturing this valuable detailed design level work as part of the architecture. Including the design information at this level can restrict design changes in the future. Instead, capture the design content as design notes or in a separate detailed design document.
Interfaces in the architecture should be defined at a high level that classifies the types, rates, and direction of data flow and controls. Keep detailed, implementation level, API definitions as well as bit and individual register and I/O level hardware interfaces in a separate detailed design document(s).
Where there is schedule pressure to define a specific interface to allow concurrent development, capture this detail within a separate detailed design specification. This will keep your architecture document manageable, useful, and maintainable.
5. Plan for updates.
During the detailed design, you will revisit and validate assumptions and decisions made at the architecture level. Also, in the process of capturing design details, you may find better, more reliable, and more elegant ways of implementing the design. Plan for the updates by creating the next revision of the draft working documents at the start of the detailed design phase, and make these available to your team. This makes it easier to capture changes as they happen, rather than trying to remember them later.
Continue to hold frequent reviews, including changes at the architecture level, during the detailed design. Use the architecture and detailed design information as a guide during the review, and update the content as you go. If you try to update when the features are complete, the information loses its usefulness during implementation, and the chance of discrepancies once updated is increased.
Conclusion
I hope you find some of my suggestions helpful. If there are areas where you disagree or have other suggestion or better approaches, please provide your feedback in the comments section. Thank you!