Part 2: Identify and Fix Underperforming Documentation

December 14, 2020
image shows a set of tools

In Part 1, I showed you how to identify the areas in your documentation that need to improve. But how do you actually fix underperforming documentation? Here are some steps to try!

Deal With Explicit Feedback

As mentioned in the first article, this fix is easy to determine. After all, if many users are confused about a step in a policy or procedure, that step needs to be updated. In this situation, it is obvious what needs to be edited because the audience’s feedback specifies what needs to be changed. As long as the author has a reliable process to collect this type of feedback (both internally from colleagues and externally from customers), making these improvements should be straightforward.

Finding the Cause of Subtle Symptoms

But what do you do if there are no obvious remedies or explicit feedback? Recall our earlier discussion of such subtle inefficiencies:

  • frustrated new employees seeking senior help due to ineffective onboarding documentation
  • quality inconsistencies within a team
  • dependencies on individuals’ undocumented “tribal knowledge”
  • documentation that does not show any obvious symptoms but would fail an audit

So how can a technical writer or team of writers prioritize and fix less immediate but nonetheless important documents?

Define the Document’s Ultimate Objective

The author must think critically and understand the ultimate goal of the document. What is the primary service that document provides? For example, a white paper’s objective may be showing your customers why a new technology is the best and most reliable solution to a well-known issue. Meanwhile, an internal training document must be able to clearly detail what steps a new employee must follow to succeed in their position.

Once the objective or service of the document is determined, the author can then figure out what topics need to be included.

Discover if Information is Missing

To find out if the document is missing any information, you will need to use your own judgement and ask for input from stakeholders. It is important that you do not leave out any essential details.

Questions you can ask, include:

  • What information is essential to understand when reading the document?
  • Is there any information the audience needs to understand prior to referencing the document?
  • Should those pieces of information be defined within this document, a new glossary, or an entirely separate document that can be used as a reference source?
  • Are there any particular pain points you or the stakeholders can foresee with the current table of contents?
  • Are there any pain points within the process the document is describing that will need extreme clarity?
  • Are there any points in the process or system that is not currently documented or up to date?

Thoroughly discuss procedures and the details that may seem obvious to some but need to be documented for all. Assume nothing!

Ensure Your Team is Prepared if Someone is “Hit by a Bus”

The “Hit by a Bus” theory summarizes why it is vital that all processes within an organization must be documented, and cannot reside as tribal knowledge. Anything could happen between someone leaving for the day and returning to work. As the theory’s title implies, they could be hit by a bus on the way home, they could be leaving for an extended vacation, or they could be leaving your organization permanently. This is why it is imperative that you have documentation that contains the knowledge staff need to carry on. This is why it is imperative that you have documentation that contains the knowledge staff need to carry on.

To avoid quality inconsistencies, a loss of knowledge with employee turnover, or even loss of capability, every process must be thoroughly documented. But how does the writer determine what is held only within an individual’s head? By asking seemingly obvious questions.

The reason tribal knowledge exists may be due to the simple fact that someone believed the information was too obvious to write down. It can be difficult when you are so close to the process to define what is obvious and what is not. So it is the responsibility of the writing team to investigate the processes, ask questions, and figure out what information needs to be documented.

As a writer, you should ask not only the stakeholders, but also those people who regularly use the document. Find out where confusion or consistent issues arise in the working processes by asking:

  • Where specifically do you need to refer to an individual instead of a document?
  • Who is that individual, and what do they know that others may not? If a senior employee were to disappear tomorrow, what would be held up, and why?
  • What tasks does that individual perform that no other employees do, or perhaps that no other employees do frequently?
  • What does that individual contribute that others do not, or that others contribute infrequently?

By using the document’s ideal list of topics, plus the probing questions, your team should be able to identify the problems in your technical documentation and fix them. The document is now freshly published and returned to its position of service! But (there’s always a “but”) how do you know the edits and updates are working?

Confirm the Remedy Works

A little bit of bad news. Updating the documentation and publishing it will not inherently “fix” the document’s problems – in fact, the wrong updates or changes could potentially harm your systems even further. That is why confirmation that the newly updated document works is vital to the entire process. This section will guide you through various methods of confirming the “remedy” works.

1. Ask for Feedback

You should ask those who had submitted the negative feedback if the updated document has improved their experience. If not, you still have work to do. But if the updates have improved your audience’s experience, then you know the remedy has worked!

2. Test the Document

You can test a document directly to see if the updates you made were successful. Establish a team to help test the document and analyze the outcome of the test. The testing individuals should not be the author of the document, nor the primary stakeholders of the document. These individuals are too close to the process.

For example, if the document details a procedure, then task a test individual to follow the exact procedure without any external help. If the test subject was able to reach the proper conclusion or final step, then the document has succeeded and your efforts have been effective. However, if the test subject was unable to reach the end of the document without questions or frustration, then the document needs more work.

Think about your intended audience, as family and friends may be a bad example to test your writing samples on (for example, if your content is stuff like API docs!).

3. Metric Tracking

And what about the documentation that was improved based on the aforementioned “subtle symptoms” which I listed at the beginning? To find out if those updates did indeed improve your documentation’s performance, set up metric tracking. Content metrics, such as number of page views and average time on page, are some of the basics to begin with. You should track the same symptoms that you identified as problems for the document previously.

For example, if the symptoms were a significant call volume into customer support about a particular topic, analyze the call volume before and after your updates. Did the frustrated calls about that troublesome topic decrease? If the document is optimized, the calls may in fact cease altogether! That is the power of effective documentation.

If the document is for internal use, did questions and misunderstandings decrease? Look at your management and senior employees’ productivity metrics such as timely completion of tasks – has it increased? Are your senior employees able to focus on their own work? You can use project tracking metrics (select what will best inform you, not all of them!) to monitor the project schedule and workloads. If staff were lagging before the development of new onboarding documentation but are now flying through tasks, less of their time has been spent helping newer employees. This indicates that the documentation is serving your team well, especially your newer employees who were previously struggling without the assistance of more experienced team members.

For documentation that details manufacturing build processes or systems, analyze your quality data. Is your manufacturer or manufacturing team able to easily refer to the procedure and consistently build quality products, despite any team changes?

If the document is electronic and mostly electronically referenced, use tracking metrics such as page scroll depth. Is there a consistent point in the document where readers stop or reference? How has that changed since updating the document? When reading a particular document, do readers often search for and open other references? Then perhaps that alternative reference information should be included within that initial document to remove obstacles to the reader.

The Power of Fixing What You Already Have

When developed, maintained, and tested thoroughly, documentation can support your team, your customers, and therefore your business’ overall success. Properly updated documentation that is accurate, clear, and concise will spur your business systems and processes to new levels of effectiveness that will drive your growth and success.

Congratulations – you have effectively improved your business from its very roots by transforming underperforming documentation into content that flourishes!