Eight Common Technical Documentation Writing Problems

Newly Updated with Podcast!


As a longtime technical writer, I’ve created documentation I’m proud of and I’ve also created documentation that wasn’t as good as it should have been. Sometimes it stunk. It happens. No matter how good your intentions are when you set out, something goes wrong in the process of turning raw information into worthwhile explanation, and you churn out a bunch of crap. All you can do is try to correct your mistakes (if you can) and learn from them. Here are eight problems to look out for:

Poor Organization

No matter how good your information is, it’s useless if your reader can’t find it. Pay attention to the flow of your information. Make your information easy to search and provide an exhaustive index. Make sure your information is available in the format your reader wants to access it in. Whether you are creating web pages, blog posts, online help files, podcasts, PDFs or print books, you need to make sure the information contained is easy to access. You need to anticipate the way the customer will approach the material. Whenever possible, observe your audience when they use your documentation and your product.

Inaccurate information

This happens all the time on technical projects. Bad information gets passed down the line and sometimes even verified by people who got the same wrong information as you did. All you can do to fix it is check, double-check, and hope.

Outdated information

This is a frequent problem with documentation projects, especially ones that are based around a product that is still in development. In some cases you get to correct this information once the change is made, but in mediums such as books and application-based help, you are stuck until the next revision comes out. That is why I prefer web-based help that can be updated independently of the product.

Irrelevant information

This is another issue that is best solved by testing the product and documentation. The product and documentation should be tested on beginners, typical users and advanced users. Each of these groups has different needs. Additionally, some products serve very different populations. There is a big difference, for example, between someone who uses a desktop publishing tool for building ads and someone who uses it for creating forms. Sometimes you can customize help to different groups and sometimes you have to build the help as “one size fits all”. It can be a difficult task either way.

Incomplete information

Users often need more information than you give them. This can be due to such things as time limitations on the project and space limitations for the help. Sometimes it is due to a lack of imagination. There also times when companies force you to hold back information. They want the user to get the basics but they want them to have to pay for training or consulting services, so they don’t let you tell the user everything you should tell them. Trust me, it happens.

You goal should be to tell the users everything they need to know without overwhelming them. In many cases, the issue is not how, but why. As the writer, telling the user what steps to take is usually straightforward (if the product is complete and functional) but telling them why they need to do this and why the result matters can be a more esoteric issue.

Bad sentence structure

The general rule of thumb for technical documents is keep your sentences short. This is especially true when writing instructions. Short sentences can be painful for experienced writers, especially those who are used to writing creative works. Short sentences feel choppy. When it comes to instructions though, you want every action to have its own sentence. You want every action to be in chronological sequence. You also want short paragraphs that are easy to read at a glance. Bullet points and numbered lists are your friends. Use them whenever possible.

Unexplained jargon and concepts

Putting yourself into the mind of a beginner can be difficult. Things that seem obvious to you are a mystery to others. Once, when I worked as an online technical support person, I had to help a woman who literally knew nothing about computers. Terms like desktop, icon, click, window, mouse and pointer meant nothing to her. I had to go back to the very basics to get her through what would have been a ten second task for me. People forget that the terms they use every day for their job often mean nothing to an outsider. Keep your user in mind.

Poor word choices

There are many words that mean approximately the same thing. For example, you might use any of the following words as a verb meaning “to end”:

  • Complete
  • Finish
  • Terminate
  • Stop
  • Discontinue
  • Close
  • Cease
  • Conclude
  • Halt

Depending on the situation, any of these words might be the appropriate choice for your document but there is certainly a different connotation when you say “Complete the process” rather than “Discontinue the process” or “terminate the process”.

When choosing between one or more words ask the following questions:

  • Which word is the most clear?
  • Which word is the most unambiguous?
  • Which word is the most accurate?

Once you have made a choice, the next step is to be consistent. Use the same word every time the situation and instructions are the same. For example, whether you wrote, Click the OK button or Click on the OK button the first time it was used in the instructions, use the same statement every time you expect the same action.

Nobody is perfect

All documents can be improved. Take a look at this article. I’ll bet you’ll find some things I could have written in a better way. You might even find some mistakes. I have no editor and I don’t claim to be perfect. The importance of editors and peer reviews is a topic worth its own article. The point is to work hard to deliver the best documentation you can deliver.

5 thoughts on “Eight Common Technical Documentation Writing Problems

  1. Hi Lillie,

    There are style manuals out there for standardization. The Microsoft Manual of Style is probably the most widely used for technical docs. I also have “Technical Writing Style” by Dan Jones, which is more of a Textbook than a true style manual but has plenty of good advice. Still, there is no overall style that everyone adheres to, and my guess is there never will be.

  2. John,

    I don’t ever expect to write technical documentation, but this is great advice. Much of it can be applied to other types of writing, also.

    Consistency is so important. It would be nice if programs were consistent.

    My husband sometimes confused on how to complete tasks, and I guide him through. Often I can’t read the text on the screen, so I say, “click OK or submit or continue … or whatever that button says.” It seems that everybody uses different terminology.

  3. For excellent Style Guides, check:

    (1) Developing Quality Technical Information (IBM Press)
    (2) Read it First! (designed by the Sun documentation team)

    Marie-L. Flacke

  4. Hi,

    There are also tools out there that allow you to automatically check your documents against style guide rules, rather than having to refer to a book or a PDF style guide.

    http://www.sdl.com/en/products/global-ams/global_ams.asp

    My blog (sorry for the plug) also talks about a few of the inconsistencies we see in tech docs:

    http://blog.sdl.com/blog/2010/04/top-5-style-mistakes-in-documentation.html

    The Chicago Manual of Style is also a good one to reference as a standard industry style guide

    Tom

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>