March 2023

Structured Content Reviews by SMEs – Challenges and solutions

Dipo Ajose-Coker, Componize

Why do we review documentation?

After all, it’s been written by a professional writer, someone who trained for years to write procedures that work and content that perfectly describes and helps the end user. So why spend extra time performing a formal review of the document?

Technical documentation is a key component of compliance and regulatory requirements, especially in regulated industries. Reviewing the content is a crucial step in the product life cycle, from creation to obsolescence. It ensures that the documentation is accurate, complete, and meets all the necessary requirements for regulatory and compliance purposes. It also ensures that it is written clearly and easy to understand, which will help prevent any potential issues from occurring down the line.

Who reviews technical documentation?

Subject Matter Experts (SME)

A term that covers many actors in an organization. Depending on the reason for review, one or many SMEs may be called on to check the accuracy and compliance of the product documentation.

Peers

Peer reviewers are typically project leaders or fellow technical writers. They typically review documentation for grammatical and style guide accuracy, as well as for structure and conformance with writing principles such as minimalism, or simplified/controlled language.

Product engineers, designers, and owners

These actors have full or near-perfect knowledge of the product. They verify that the content fulfills the requirement of being complete and informative. They check whether the documentation covers the latest product information such as screenshots, steps in procedures, part numbers, and other details.

Legal, complaints handling, and marketing departments

The legal department intervenes especially in the case of a new product to ensure that items such as product names do not violate trademarks. If the product uses third-party subsystems, that information must be provided in the documentation, and any proprietary information must also be declared as such. The marketing department typically makes suggestions or takes content from the product documentation to build marketing materials or product datasheets.

Risk analysis & corrective and preventive actions (CAPA) leaders

Risk analysis is carried out on all products that have a potential to cause harm, directly or indirectly. Where risks cannot be mitigated by design, they are mitigated by documentation. A risk analysis leader will review a document to ensure that all risks in the Cause/Mitigation database are matched to a safety notification or information in the documentation. A CAPA leader will typically review documentation when investigating the root cause of an issue that has occurred in the field.

Regulatory Affairs and Certification leaders

These are the principal SMEs when it comes to product documentation in regulated industries. Here the product must provide a minimum level of information about the use and maintenance of the product. If the product is subject to standards, the Regulatory Authority will require that the documentation contains information required to prove that it meets minimum standards required for that product. In the case of product certification, the documentation provides some of the information required by those standards.

What are some of the challenges?

Convoluted Documentation Review Workflows

Most of the issues we face, I can quite honestly state that we inflict on ourselves. We created workflows, but rather than finding the simplest one to follow, we make them increasingly complicated, sometimes in good faith.

An example of an overly complex workflow

Quite often the document review workflow looks like this. In this document review workflow, 5 tools and many processes compete for attention.

Requirements Database – IBM DOORS for example, but also anything used to store requirements, JIRA, Excel, etc.
EDMS – Electronic Document Management Systems for document and records management. Sometimes used during review to track approvals.
CCMS – Component Content Management System. Componize DITA CCMS for example.
Document share systems/platforms – Network/Cloud storage solution. Often used to distribute drafts for review. Also includes emails, SharePoint, and instant messaging in this category.
Delivery Platform – The final destination from where the intended audience is supposed to access documentation.

What’s the issue? Too many tools, sometimes overlapping in duty, and swimming from lane to lane.

Lack of collaboration/increase in silos

We have the tools and technology to collaborate especially in this “relatively new” world of remote working. However, we continue increasing the spaces between us and creating Silos. This is either out of self-preservation or a misguided approach to working practices, some managers think their teams work better isolated from the rest of the structure in order to keep concentrated on their tasks.

Silos within an organization lead to conflicting schedules and priorities.

The SME might not be in the same headspace as the technical writer due not just to their task prioritization, but also due to the multiple systems and tools in use within the organization.

There is also a multiplicity of role-unique tools.

As seen in the complex workflow presented earlier, each role within the organization can have one or more tools used to perform their tasks. The transfer from one tool to the other or the time it takes to wrap our brains around how the other tool works can lead to incompressible delays in workflows.

Lack of SME engagement in reviews

When asked, many SMEs will admit that they consider document reviews as a peripheral part of their job. Unless reviewing documentation is listed as a core task, some consider it an inconvenience. They would go as far as to suggest that if they must review the “content”, they might as well write it themselves. If reviews are not explicit in the list of SME tasks, many will consider it a low priority aspect of their job.

There are other aspects to consider as to why SMEs are reluctant to review content

Learning curve for the non-technical reviewer

There is a lack of adequate tools to review XML source content, and for the few that exist, they require SME training. No matter the XML editor, we as technical writers must admit it takes getting used to. Training someone to use a tool that they will not use for another year is a waste of time. Think about your learning curve when you first encountered Adobe FrameMaker: How many of the functions can you honestly say you fully understand and remember how to use? How do you expect someone who uses it infrequently to hop into the tool to do something they are not necessarily in the mood to do?

So, we have now come to the point where you need training in order to use the review part of your CCMS before being able to review a document. That learning curve is too dear for an SME to make the investment. “For a few hours of work, I have got to go through a few days of training? No thanks, send me the PDF please!”

Some challenges are specific to structured content.

Complexity of reuse and a lack of adequate tools

The reuse process is complex. It requires a deep understanding of the content strategy and the information architecture that has been designed to support it.

The challenge is not just the technical requirements of reuse, but also the cultural shift that is required to get people to think differently about content. It requires a change in mindset so that all stakeholders see their role as contributing to a common goal of reusable content. In addition, there are risks that need to be managed throughout the process (e.g., regulatory compliance issues, intellectual property risks).

A simple no-tags view of an XML document is not a solution.

Reviewing structured content in XML requires training
There is a cost in time and money training an SME to use an XML editor for just 5 days a year
The content is exposed to a risk of introducing visible and invisible defects, for example:
- Hard coding content that should be a conref, key or variable
- Copy/paste of content as opposed to using the correct reuse mechanism

Mistrust of source content reviews

An example of overcomplicating things is an insistence on PDF reviews as opposed to reviewing the source content in the CCMS. Some of this is based on a misinterpretation of an FDA requirement that information provided in submitted documents must be in a format that cannot be easily changed or modified without an appropriate level of traceability. This is interpreted to mean PDF or, in the past, paper documents are the only acceptable formats. A long time ago, paper and PDFs were quite difficult to falsify. Paper left traces, as did a PDF. This “truth” is no longer valid. My last search for free pdf editor resulted in over 1.3 million hits. From which you can find at least 10 good multi-platform apps that will do a good job of allowing you to modify a secure PDF Document.

So if these formats are no longer as secure as they used to be, why continue adding a step to the review workflow that forces documentation teams to publish and extract PDFs, place them in a separate EDMS for the approval of the contents before submission? Why not just trust the version and permission controls included in any half-decent CCMS to approve the content and only take that final version out for submission.

How many organizations review source content in their CCMS?

A Componize survey of over a 130 CCMS users in 2020 revealed the following statistics.

Organizations have invested (sometimes significant amounts of money) in a CCMS, however they are not using the full potential of their system, at least or not all the time when it comes to reviewing source content. After having invested so much in a high-end system, they’ve reverted to the comfortable PDF review of the 20th century!

Time Wasted in Final Output Reviews

Identifying and highlighting changes in the output document
Publishing and exporting the PDF from CCMS
Uploading to a shared drive/attaching to email
Collating feedback and comments
Creating and maintaining tracker documents

Inefficacy of PDF Reviews

Challenges specific to regulated industries

Compliance

Technical documentation compliance risk is a challenge that many companies face, especially in the regulated industries. Complexity of the CCMS and its integration with the Quality Management System of the organization. However, studies have shown that when correctly implemented within the organization’s QMS, the organization is less susceptible to risks arising out of incorrect, outdated, or unclear content and documentation.

Change Management

In the Life Sciences industry, manufacturers must adhere to requirements governing the design history of registered devices. Making changes, verifying, and validating them, is anything but fast. It involves multiple people and stretches across multiple functions.

A change request involves identifying changes and the impact on the product and its documentation, performing risk assessments, and reporting. Poor document control leads to frustrating and often frantic sessions where documentation and engineering teams try to piece together the modifications that were made to a product and its documentation.

Organizations must be able to demonstrate that content is secure from unintentional modification.

How can we improve the review process?

Analyze and improve workflows

Do you remember the workflow from earlier? Well this one is a slimmed down version. Take out redundant tools and systems. Rather than extracting your document from the CCMS, why not use it, the CCMS, to send the content for review, even if you insist on reviewing a PDF. Some CCMS have a document management function that is able to provide governance services and records management. These features can easily replace the EDMS and Document-Share swim lanes present in the previous workflow.

Connect CCMS & Planning tools

Linking review tasks directly to topics/maps during project planning will allow you to track progress more accurately, have a better analysis of impacts on other parts of the documentation or even the product. A link between both systems can generate auto-notifications if/when there is a change in specifications, triggering an instant notification of content creation and review tasks. Most importantly, a principal advantage is that this keeps the documentation team visible during the planning phase as opposed to during sprint execution.

Content as a Service. Avoid seeking to cram every content type into a single system. Instead, connect disparate systems where needed, so each content group keeps their unique workflow.

Use CCMS Workflows

If you have a connected system, then why not use the workflow tools available in each. If you use your CCMS workflows, then there is less chance of missing someone or something out during the approval cycle. Once the workflow is set up, the advantage is that is can be used by all, thereby standardizing the review process across writers/departments. The CCMS is able to track all changes to content, but also, who said what, when and why, and the resolution actions that were taken. Your workflow can set permissions so that right person receives the right instructions and is only allowed to perform the tasks assigned to them. Can you imagine your workflow automatically creating a “For Review” branch as soon as you send a document for formal verification review? Writers can keep working seamlessly on the trunk content, safe in the knowledge that the content under review will not be inadvertently changed.

Improve Output Format Reviews

Share in advance to set expectations, identify problems, and clarify goals. Before starting the review process, sharing drafts and thoughts on the content with the reviewers in advance allows them to have a clear understanding of what they will be reviewing and what the expectations are for the review. This also gives them a chance to identify any potential problems, disagreements or issues so they can be addressed before the formal review process begins. By clarifying the goals of the review, the reviewers can focus their feedback on the key areas they have been assigned.
Seek feedback from SMEs before requesting reviews. By seeking feedback before requesting reviews, you can reduce the number of review cycles and increase agreement on the quality of the work. SMEs can provide valuable insights and feedback that can help improve the quality of the content before the actual review process starts.
Establish review rules to eliminate confusion. Establishing clear review rules can help eliminate confusion, ensuring that everyone involved in the review process is on the same page. This includes setting deadlines for the review and the format of the feedback you need. You can also agree on the process for resolving any conflicts or disagreements that may arise during the review process.
Engage with your SME during the review process During the review process, it is important to engage with SMEs to better understand their feedback comments and to clarify questions or contradictions you may have. This can help ensure that the feedback is interpreted correctly and that any issues or concerns are addressed in a timely and effective manner.
Educate all actors involved in the review process Education is crucial to the success of the review process. This involves training and educating everyone involved in the review process on the expectations, rules, and goals of the review process. By ensuring that everyone has a clear understanding of the review process, it can help improve the overall quality of the work and reduce the number of review cycles.

Adopt synchronous reviews

To foster real-time communication between SMEs
To reduce conflicting feedback
To reduce time spent collating feedback

There is a time and a place for everything. While there is this great debate going on about synchronous versus asynchronous working, there is no one solution to all situations. Sometimes it is best to clarify contradicting feedback with the multiple SMEs involved. For example, a request from the marketing department to include some information might need to be rewritten on feedback from the Regulatory department. The added weight of the counterargument coming from the regulatory leader rather than the technical writer might convince the marketing leader requesting the change.

Limit output reviews

Stop wasting time! Save the final target output review till last. Instead of 750 pages of content to review all at once, the SME only sees that final version once, at the end of the draft cycle. They have already seen the bits of new or modified content and have pre-approved it. The SME then just has to approve the final presentation of the complete publication during the final review cycle. Your CCMS can provide a change report of all the topics that have changed version since the last approval if the SME needs confirmation that nothing else has changed.

Use publication parameters to automatically highlight what has changed, with varying degrees of granularity.

Review Incrementally

Instead of reviewing the entire document at once, it is often more efficient to review the content incrementally based on topics. This allows the reviewer to focus on one specific area at a time, which can help to reduce the amount of time and effort required to review the content. It also makes it easier to identify any issues or concerns in a specific area of the document.

Use your CCMS to track changes

All CCMS allow you to track changes made to the content and easily identify what has been changed or updated. Use this feature combined with the next point to streamline the review process and make it more efficient.

Ensure that changes to content are easily identifiable

When making changes to content, it is important to ensure that they are easily identifiable. When setting up your CCMS publication pipelines, ensure you also create a parameter to automatically highlight changes in content from one version to the other. This helps to reduce confusion and can speed up the review process.

Include technical documentation teams in agile planning

By including technical documentation teams in the agile planning process, the documentation is integrated into the overall project plan and is not an afterthought. Review tasks can then be included in the sprint, and assigned to the relevant SMEs.

Create task-based reviews

Start creating task-based reviews

This subject could easily be an entire article.

Once integrated in the agile planning, creating task-based reviews allow you to break down the review process into smaller, more manageable tasks. Assign specific tasks to reviewers to ensure that each task is completed as any other task would be in the sprint. This helps to streamline the review process and make it more efficient.

When creating a review task, it is unhelpful to send the same review message to all SMEs every time you need a review. The reason and target of the review should be clear to each reviewer.

A task based review takes into account the state the document is in, (first draft, formal review, values review) and the role assigned to the review (peer review = style guide, grammar, Certification Review = check that I have not left out important information required to achieve certification, but you can ignore typos).

Conclusion

After having spent considerable sums investing in a CCMS, organizations are still not reaping the full benefit of such robust systems. The ROI can be improved considerably by implementing some or all these strategies. Organizations can improve on the time and effort spent reviewing technical documentation.

Read more on how you can improve the different aspects of technical documentation reviews on the Componize blog.

About the author:

With over 16 years combining languages and IT as a technical writer and editor working in regulated industries (high-end medical devices and finance), Dipo blends his experience of authoring in structured and unstructured environments; migrating technical publications to DITA; and content strategy to help develop a best-in-class CCMS. Dipo holds an MA in Multimedia and Multilingual Document Design