I recently presented this content at a meeting of the Greater Houston Chapter of APMP.
To see my presentation, you can review the SlideShare here.
We all know that, when it comes to a technical documentation, content is king. If we don’t have good, accurate, complete content, our documentation will fail. We can nail the grade level of the writing, and have excellent organization. However, without excellent content, those things are meaningless. Content is the King.
But at the same time, we can have great content that fails. In those cases, King Content is deposed, overthrown by issues that should never come up in the first place.
So what are the problems that ruin good content? Who are the plotters that overthrow King Content, and put the focus of our writing exactly where it should not be?
1. Overly complicated writing
A quote from Warren Buffet’s preface to the SEC Plain English handbook:
“Perhaps the most common problem, however, is that a well-intentioned and informed writer simply fails to get the message across to an intelligent, interested reader. In that case, stilted jargon and complex constructions are usually the villains.”
We must always ask ourselves a question when we read any technical document. That question is: “Did I understand this the first time I read it?” If a user will not understand the sentence, paragraph, or document the first time they read it, then you’ll probably lose them.
Now, it’s one thing to read something that someone else wrote, and identify some issues. But what if you wrote it yourself? Just about anything you write will make sense to you, since you’re the one who wrote it. And putting a document away for a couple of days isn’t a luxury we always have.
So what do you do? Use metrics. If you’re using Microsoft Word, then this is easy. Just enable the readability statistics add-on for the spell checker. Then you can review anything from a single sentence to an entire document, to see if it contains an appropriate level of complexity.
For the steps involved in enabling readability statistics, see Microsoft’s article on the subject.
2. Vendor-focused writing
“One the biggest problems with the text in proposals? Talking about your own company WAY TOO MUCH! The focus should be on the client. I try to use the rule of using your clients’ name three times more than your own.”
Proposal Writer at RTL Networks, Inc
It’s easy to slip into the habit of focusing on our own company, or our own technology. For documents that are aimed at a particular client, we may wind up talking about our company and its solutions much more than we discuss the client and their needs. Oil and gas companies may focus on their equipment or services, and forget that the client doesn’t care about those things (they only care about their needs). Software companies may produce documentation that delves deep into the inner workings of their product, but that doesn’t address how the features actually meet the customer’s needs.
What do we do to resolve this problem? First, count.
How many times in the document did you mention the client and their needs, versus your versus your own stuff? If the ratio isn’t at least 2-1 or 3-1, you may have a problem.
We can skip a lot of the problems associated with vendor-focused writing if we’ll take the time to plan the focus of the documentation up front. If we’ve decided as a team not to focus on ourselves, we’ll be more likely to wind up with the right result in the end.
But what if you have already received a document that is obviously written in a vendor-focused way?
You’ll need to perform triage. You need to know which sections are most important in the document. Is the most important section the executive summary? Is it the introductory content? Is it a key procedure midway through the document? Identify the key sections, and make sure they’re as client-focused as possible.
3. Glaring text errors
“Do not tolerate any mistakes.”
Elite Documentation Employee Standards
This one is pretty simple. You can handle it by reading over the document, and asking “Does any of this make us look dumb?” And “Which typos might make us look the most dumb?” Again, prioritize, and focus on sections and types of errors that could do the most damage to your company’s professional credibility.
Using a different set of eyes really helps for this one. I’ve become a very good writer, but I’m not God. My writing is almost never completely free from errors. No one’s writing is divine.
4. Schizophrenic writing
“Different authors may yield different styles or voice. These differences may also manifest themselves with the facts … Somebody has to do a “horizontal alignment” check.”
Principal at A&M CoOp
If you start encountering a lot of different voices in your technical documents, you should ask yourself, “Do we have a pre-existing standard?” When deadlines are looming, it’s not the right time to come up with standards. The right time to come up with writing standards is before the project even kicks off.
I remember working on a $1.5 billion proposal a few years back. I fielded question after question about what the “right way” to format something was. I helped the team come to consensus, but I couldn’t help wondering to myself, “Why are we just asking these questions now?” Companies need to have a style guide before writers even start working. Otherwise, decisions become very haphazard.
It also helps to have a rational workflow. To explain what a rational workflow might be for your company, let me explain the different kinds of editing that your documents need. (Keep in mind, I’ve written some of the following information from a proposal writing perspective. The workflow you use in your company might be much different. The important thing is that your workflow makes sense, and produces good results.)
Once you’ve gathered your content, it’s time to do a substantive edit. The substantive edit is different from the proofread in that a substantive edit asks the question, “Does this really make sense? If not, how can I rewrite this sentence or section or table header to make sure it does make sense?” Of course, depending on the volume of work that you have, you might not be able to do a substantive edit on all of your content. You need to prioritize which sections have to make sense. Then focus on making sure the writing in those sections is crisp and clean.
After the substantive edit, it’s time to proofread and copy edit. This will be relatively quick easy if you have a good set of standards. If you don’t, people will continuously make adjustments based on their own preferences. That will reinforce the schizophrenic voices that you are trying to silence.
5. Embarrassing boilerplate
“Nothing says “I don’t give a fig” like calling the customer Acme Manufacturing when their name is Amalgamated International.”
Head of Bid Management at Bull Information Systems
If your documentation projects tend to be similar, but not exactly the same, for each customer, then you may have seen some embarrassing boilerplate. (Boilerplate is text that is reused over time for multiple clients or projects.)
If you use boilerplate, you must ask yourself, “Which parts of this document will I need to customize for this customer?”
You need to have a list of the places in each document where you need to customize the information. You don’t want to get in a crunch, and then have to search frantically for each instance of text that refers to a different customer. You won’t find everything, most likely.
For this effort to make sense, you also must have a good style guide, with standard terms your employees should use. This will help you with global searching and replacing, especially in Microsoft Word. If you refer to a customer as ACME, ACME Inc., ACME Amalgamated Inc., and ACME incorporated, you will have a much harder time getting everything updated.
Boilerplate tends to hurt the quality of many kinds of documents. But in the software industry, and in certain industry niches, boilerplate is critical.
May this this article help your content grow stronger. Long live King Content!