How to Know if Your Technical Communication Deliverables Are Successful

This is one of those blog posts that sounds simple but is quite difficult. How do you know if your technical communication deliverables are successful? Is success even the same thing for different types of technical writing? How do you measure the success of a policy and procedure manual vs. a product installation manual vs. a software product online Help system? We are not even five sentences into the blog post, and we cannot even nail down a definition of effective communication.

Sometimes it is easier to approach this from the opposite concept. There are several reasons that a technical communication deliverable can fail, and by examining those failure points, perhaps we can derive success criteria and metrics. If you are looking to improve your technical communication skills, you have come to the right place.

Common Points of Failure in Technical Communication

Starting to Write Without Having a Plan

Before the first task or concept is documented there are some fundamental decisions that need to be made. What is the goal of this technical communication project? Do not assume the goal is obvious, all stakeholders need to agree. If you think that the goal is customer satisfaction, but another stakeholder thinks that the goal is reducing product returns then the seeds for failure are already being planted. Make sure that the goal is well defined, documented, and agreed to by all stakeholders before beginning so you have a uniform plan on how you are going to reach your intended audience through your communication channel.

Not Having a Style Guide

Your Style Guide should define the details that establish your corporation’s “voice” when reporting on technical information. Paper sizes, approved fonts and sizes, official colors and when/where to use, rules for usage of corporate logos, rules for usage of product logos, and on and on. It is extremely easy to spot a technical communication project that was lacking a Style Guide. It is usually hundreds of pages of ramble and inconsistent look and feel. Your Style Guide should even provide guidance on items like the use of industry jargon or even something like the use (or non-use) of the serial comma so that all authors will be consistent.

Not Building Topic Templates to Support Your Style Guide

One of the best ways to help the team to publish cohesive and consistent content is to use the capability in MadCap Flare to create your own custom topic templates. First, do a content audit. Determine the exact types of content that you will have. Different authoring models change the vocabulary and labels but most content falls into very defined categories. If I expect the reader to be able to do something with the information I write, that would typically be a Task or Procedure type of topic. A topic that includes background information would be a Domain Knowledge or Overview type of topic. Your content audit will help you to identify the exact topic types that you need to support. Then mockup the perfect example of each type of topic in Flare and “Save as template” from the File menu.

Not Having an Outline

Many just want to dive in and start writing. This can be a mistake. We need to make sure that every word written meets the needs of the customer and supports the goal we set way back in item 1 of this list. The best way to reach that end, and also a good practice in DITA technical writing, is to establish an outline before the writing even begins. One technique that I like to use is to open my Flare project and use the Flare TOC editor as my outlining tool. The local toolbar of the TOC editor has an iconthat will add a new page entry to the TOC and create a linked topic in the Content Explorer at the same time. The added benefit is that once your TOC outline has been created you now have all the empty topics ready to be populated.

Not Fact Checking Your SME (Subject Matter Expert)

This might seem like an odd one, but one I have learned through scars and troubles. People may disagree with me, but technical documentation is sometimes the last line of defense for the customer. More than once I have received an “approved” procedure from an SME and it just did not look quite right. A little fact-checking later, and it turns out that it was in fact, horribly wrong. How can that be? They are experts! In the case that I am thinking of, the SME was a PhD-level scientist that worked in an R&D prototype lab. The procedure they had written did work, but only in their lab. You see, they had removed all the safety equipment and guards from the prototyping machine. As written, their procedure could not be performed on a production model that was shipping to customers.

Not Measuring Results

This is a big one but is often ignored. The problem is that measuring results is rarely easy, especially when it comes to technical documentation. The biggest mistake is measuring the wrong thing. As is often said in Six Sigma circles, “You get what you measure”. However, the corollary to that is that if you measure the wrong thing, then you get the wrong results. The key is going back in this list to item 1.

How to Know if Your Technical Communication Is Successful

What was our original goal? We need to make sure that whatever metrics we choose to measure truly indicates the level to which we achieved that goal. If the goal of our business communication was customer satisfaction then we will need to develop a way to get that information from the customer audience. Perhaps a survey, or customer sampling via phone calls. If our goal was to reduce product returns, then we will need to work with product management and sales to determine what the baseline product return numbers were before we started and how those numbers have changed a set number of months after the technical communication project was delivered.

Summary

The moral of this blog post is that determining “success” requires both good goal setting at the beginning of the project and quality measurements after delivery. If the initial goals were wrong, or if the wrong data is measured, then we will not have a true gauge of success. This reinforces that success at technical communication does not happen by accident, but by doing the proper upfront planning before the writing even begins.