This guest blog post was written by Madelyn Boudreaux, a technical writer with over 20 years of experience in her field.
Using Concepts Tags to Speed Requirements Traceability in Regulated Documentation
Writing for engineered products, particularly in regulated industries, often involves meeting specific requirements, both those that outline the product design and use and others that are required by regulating bodies such as the FDA or FAA. Design requirements flow from customer needs and internal design standards. Regulatory agencies may require standard and industry-specific requirements; for example, medical devices are required to provide operating and storage conditions, cleaning and sterilization procedures, and a whole list of specification information. Companies must perform risk analyses that outline all the possible failures; these are often mitigated through precautions in the user manual or Instructions for Use (IFU).
All of this adds up to scores or even hundreds of pieces of information that must be included in a document. Each item – from weight and dimensions of a device to the ideal humidity for its storage – must be regularly maintained as devices change over time. These requirements need to be easily found and tracked by the technical writer and Quality Assurance (QA) for Verification and Validation (V&V) activities.
This article offers a few ideas for how tracking requirements in your content can greatly improve your writing, auditing, and V&V outcomes, providing smoother content maintenance, improved internal customer support, and faster QA turnaround times.
In one example, I worked with a company who had 4-5 versions of a medical imaging system. Each product was similar but had detailed differences such as motorized vs manual controls, tube-based vs flat panel displays, and 2D vs 3D imaging. Each product had hundreds of requirements covering systems, subsystems, user interfaces, and high-level regulatory expectations.
When I began working with the company, I discovered that the QA team was checking the existence and technical accuracy of these requirements manually. Two employees sat side-by-side, searching each 500-page printed manual for some text that seemed to meet a requirement, and then ascertained if the content was correct and fully met the requirement needs. It took 80 hours, as two employees took a full week to check each manual. Of course, requirements were sometimes written in engineering-speak and then edited to be more user-friendly in the final content so the reviewers couldn’t just search an electronic document. They not only had to find content that looked very different but then had to ensure that it was accurate even when it was not written in terms that related to the requirement. It was slow and arduous, and the process had to be repeated every time a manual changed for every product.
That kind of rote work is a morale killer for most people, and I vowed I'd find a solution.
My solution was to use MadCap Flare's Concepts.
The manual content was already in Flare, so I found every piece of content that met a requirement and added a Concept named with the requirement's unique ID. For example, if requirement URS1823-56 stated that the product documentation must include information about the monitor resolution, I tagged the resolution specification topic with a Concept called URS1823-56. In about 2 weeks, using notes from the last QA engineers who had checked the manual, I had a full library of requirements in Flare.
I then added a Concepts proxy to the end of each TOC, just after the Index. This proxy was normally hidden and did not build in most outputs. However, when V&V were ready to check a manual, I’d switch on the Concepts proxy and print it.
These Concepts filled a few needs. It was very common for an engineer to come to my desk and ask, "Do we cover requirement URS1823-56 in the manual?" I could open the Concepts panel and see all topics that included the requirement as well as which Targets included the Concept and thus fulfilled the requirement.
Additionally, some change requests would note that a requirement itself had changed, and I could quickly find the content that met that requirement and make the change. More commonly, I received change requests that didn’t reference a requirement. In those cases, the presence of a requirement Concept in the content would remind me to find out if the change affected an existing requirement. This meant I could let the architects know to reconcile the change and requirement, so nothing ever got changed without the architects knowing. This was a huge benefit, since in this large organization, not every employee knew what was going on in another department, even when the work affected other parts of the system.
We often batched a few unrelated updates under named programs. For example, we might have a program that added a new brake, included a few software changes and updated or new UI screens to support these changes, updated verbiage to meet a new FDA requirement, and included new cybersecurity changes. Often, these changes cascaded through multiple versions of the imaging system, affecting each product differently. I learned to use Concepts to tag content changes with the program so I could quickly produce a list of every Topic that had been updated for a given program.
It was exciting that, over time, the engineers and managers came to understand that I’d built traceability into our content management system. The requirement documents themselves were managed as an enormous, interlinked database, and the engineers and architects loved being able to see a direct connection to the content that made up our product documentation.
But the real coup came when V&V needed to check the requirements in the document. I could provide them with a PDF along with a copy of the Concepts proxy built as part of the Target. This "Requirements Map" gave them 3 pieces of information:
- The internal requirement number, such as URS1823-56.
- The content (text, heading, etc.) that met that requirement, such as the specification related to monitor resolution.
- The page number on which the content could be found.
As I mentioned above, the old method took about 80 hours, which was typically 2 employees working together for a week. The Requirements Map brought that time down to 16 hours. They were able to check the entire 500-page document in a day, with one person following the protocol and the other quickly going to the correct page and finding the text provided in the Requirements Map. While there were certainly some initial misgivings when I introduced the Requirements Map, especially on the part of managers who didn’t feel the heavy toll of that work, once a few people had tried it and finished the work in a fraction of the time, everyone was on board, and we never looked back.
I’ve used Concepts for other things too, but it was the V&V use that was most visible and saved the most time and money, not to mention the sanity of the engineers tasked with checking that the IFU met all requirements.
