It is a truth (near) universally acknowledged that software engineers detest creating documentation. And the documentation they do like to generate is usually not readable by anyone who isn’t a software engineer.
All of this is an issue when you have software for products in highly regulated markets, such as medical devices trying to meet IEC 62304.
But can you blame engineers for not wanting to get involved with creating docs? In many development environments, creating documentation isn’t an ongoing process. Here, completing documentation needs to happen before the next piece of the project can be worked on. Then bringing everything together for auditors becomes an arduous procedure that can take weeks at a time and a monumental amount of effort to produce.
Attempting to develop software in an Agile or Lean-Agile way could help alleviate this drag on time. But even the guidelines in AAMI TIR45, which shows how to deliver medical device software in a compliant and Agile way, can cause an increase in development times as teams try to create documentation.
How can we make documentation generation a more straightforward, efficient, and effective process where the final documentation keeps auditors happy?
What is living documentation?
It’s documentation that’s generated as part of the typical software development cycle, pulled together using automation to create auditor friendly documents. It looks like this:
So, all the documents that engineers and testers create as part of their actual software development method and testing are automatically brought together. And it means that the latest project documentation is fully version controlled and just a button push away.
Living documentation works best in Agile and Lean-Agile Software teams
In our blog post on automated testing for medical devices, we previously discussed how automated testing could help Agile and Lean-Agile teams working to TIR45. Living documentation can work with TIR45 in a similar way for teams.
What do we mean by Agile or Lean-Agile? Here at Bluefruit, we see Agile as three tiers with Lean software development being a part of it:
In TIR45, the layers of development and activities that are going on as part of Agile or Lean-Agile practices are spread across it. The layers (project, release, iteration/sprint, story) look something like this:
In bringing living documentation into the practices of an Agile or Lean-Agile software team, the task of sorting out documentation becomes far more manageable and less time-consuming.
Living documentation can help teams overcome the documentation drag
Living documentation is easier to bring in with teams who are following the technical practices that you find in Agile and Lean-Agile ways of working. The artefacts created from these kinds of techniques are ready to be brought together in documentation with a considered mix of technology to automate the whole process.
It’s possible to combine:
- Behaviour-Driven Development (BDD) feature files
- Test-Driven Development (TDD) test intentions
- Other project documents and engineering documents that are produced alongside the project
on a build server, and then assemble it all, version check, format and so on. The output is a wiki-style HTML format document or a PDF document, or a Word doc automatically outputted (or any rich text document, with branding). And that document is sent to a document management system. Basically, at the end of all this automation, you have an auditor and compliance team-friendly document.
In embracing a living documentation approach, all those engineering activities that software engineers love and are doing already? The same tasks that they’re doing every day? Those tasks create documentation without creating more work for engineers and the compliance teams needing to work with them to get the documentation right.
So, instead of documentation happening last, it’s ongoing and up-to-date and doesn’t take weeks to create.
By having living documentation, you go from a documentation situation like this:
(Our engineers know which way they’d prefer to work when involved with projects that have acute compliance needs.)
Living documentation can reduce the (overall) time teams take to produce documentation for traceability and auditing. Instead of the engineering team spending weeks on it, the process covers just a few days in the release cycle.
Hang on: this is all looking rather technical, our compliance team are not engineers
During his webinar “How to achieve shorter release cycles for medical devices”, Paul Massey (Bluefruit Software’s Founder and Director), explained that it is easy enough to automate compliance team-friendly documents.
The creation of the infrastructure for getting docs together? That will take technical know-how, but with the right processes and communication between the software and compliance teams—you can get the mix of documents the compliance team needs whether it’s Word docs or PDFs or an interactive mini-site.
Getting it right does mean it’s essential that the build server pulling everything together has explicit version control. (A platform like Git can help with this.)
The differences in introducing living documentation in greenfield and legacy projects
It’s not a simple act of just introducing living documentation to a team’s processes. It does depend on their starting point and the overall organisation.
Like we’ve said here, if your team is already working in an Agile or Lean-Agile way, then they’re already well placed to begin introducing living documentation.
But how long it takes to introduce living documentation depends on whether you have an existing project, or a new project unencumbered by existing systems or infrastructure, or customers.
Greenfield: Teams will likely need two to four weeks to get the infrastructure set up while working on other tasks simultaneously.
Legacy: Teams would gradually introduce living documentation in this scenario. Here it would take at least a few months for a living documentation process to mature.
If you’re bringing in the process entirely through an in-house team, and your team isn’t already familiar with it, then the lack of experience will also mean that introducing it will take time. Outsourcing or involving people who have the expertise and the toolkit you need, all ready to go, will cut down on time here and help reduce the overall investment cost.
Living documentation takes investment
As with test automation, realising living documentation as part of a software development process will take a degree of investment. More so if the team isn’t already working in an Agile or Lean-Agile away.
But the benefits of freeing up engineering and compliance teams from the main work in this task will pay back quickly. Instead of being dragged down by documentation, teams can sooner move onto planning and starting the next software development sprint; safe in the knowledge that the documentation produced in real-time is of a higher quality and in line with the current state of the software.
Watch the webinar “How to achieve shorter release cycles for medical devices”
If you didn’t get the chance to watch Paul Massey’s webinar on how you can cut release cycles for medical devices, you can watch the full webinar below:
Insights: software development for medical devices
Does your latest project need a AAMI TIR45 savvy embedded software team?
Bluefruit Software has over 20 years of experience providing high-quality software development, testing, and consulting to clients in a range of sectors including medtech. In the past five years we’ve worked on seven different medical devices, providing software development and testing to help our clients create products that meet IEC 62304. Want to talk?