Why does documentation "suck"?

One of my tasks for slow periods at work is to troll the User Forum to read what our customers are having problems with. Each time we release a new version, there are plenty of posts to keep me busy. If I had any sort of ego, I would be severely depressed reading some of the posts that say “the documentation sucks”! OK, it doesn’t happen often, but it happens. And almost every time I read or hear that, I can point the complainer to the exact topic that they didn’t bother to read before stating that the documentation sucks. Yeah, you are correct—the search sucks. It’s not Google search. And yes, when you call tech support, we have a great group of guys who can hold your hand as you walk through the tedious process of creating a chained certificate. But before you blame the documentation, at least make an attempt to read it. All of it! Scroll through the Contents or Index, or type text in the help’s Search box (NOT GOOGLE) and press ENTER. That word got no results? Try another one! Read a few results to maybe clue you in to what words you should be using. Try those words. Read a few topics. You might learn something. You won’t waste your time, because next time you have a problem, you might need that exact information.

Why does documentation “always suck”? Below are several reasons:

8) Too many cooks in the kitchen. You’ve hired a technical writer who is both technical and a writer (yeah, doesn’t always work that way), and yet everyone wants to tell her how to write. Let her write it. She knows end-users better than you think and has experience writing to that audience.

7) Several different locations are available from which the end user tries to get help: in the application, online, PDF, knowledgebase, user forum…and that’s just the locations we can control! Something is bound to get lost in the shuffle—or too much salt added to the soup, to continue the “cooks” cliché.

6) Companies like to save money. Why would they hire a highly-paid programmer to spend his day writing documentation? And if he’s a programmer, why would he want to? Besides, developers tend to be very advanced in their field and talk way over the customer’s head. (“Everyone knows that!”) The customer wants to know “what grade of oil should I use in my car this winter?” not “how does the internal combustion engine work?” (Note: I have met programmers who write very well to an end-user audience. But they are rare. Many write “to please the teacher” rather than to have their communication understood.)

5) Companies like to save money. They are likely to hire “Bob’s cousin, Milly who’s really good with Word” as their technical writer. Sadly, Milly barely knows how to lock her keyboard, has never used a help-authoring tool, and certainly doesn’t know how to install beta, undocumented software on a virtual image. The developers then, begrudgingly, write most of the documentation—-which is way over the head of their customers and Milly.

4) And by the way, companies like to save money. They often hire someone who not only cannot install and use beta, undocumented software on a virtual image, but also cannot write complete, lucid sentences. At those times when the technology is way over her head, a good technical writer can identify the nouns, verbs, and objects in the sentence, put them in the correct order, and actually make sense of it; or she can bug the developer until he explains it to her in plain English.

3) Developers are busy and don’t want to document how to use their product. “Why, my product is very user friendly and intuitive! We don’t need a user guide!” This is where the technical writer’s interview and annoyance skills come in handy. A developer will eventually get tired of her questions and actually provide helpful information to a technical writer. (He would just blow Milly off, because she wouldn’t understand anyway.)

2) Sometimes (OK, usually), the release cycle is more important that the documentation. The documentation is delivered and signed with help content that is a week or more old. (A lot can change in a week of QA!) In my case, I update the online help and knowledgebase as new issues come to light. (See number 7.) But I’m occasionally left out of the change loop.

1) And finally, the number one reason “documentation sucks” is that it sits unused. The customer doesn’t want to “bother” to read the whole user guide, which could be thousands of topics. Average Joe Customer wants to click Help and have a window appear with a hand that reaches out from the monitor, types the information that he needs to specifically answer his question, and pats him on the back, telling him it will be OK. Dream on Joe. You have to work harder than that.

Here are a few Frequently Asked Questions about Help documentation:

Why did you put THAT in the help? Everyone knows THAT!
Nope, sorry, Mr. Engineer, but not everyone knows how to find the capacitive reactance of a parallel circuit, even if you think it’s a prerequisite to using our product. While we’d like to believe that everyone who uses our product is at least as smart as you, the truth is, we aren’t.

Why didn’t you put THAT in the help?
Because I document *our* product, not Microsoft’s, Oracle’s, and Java’s. Granted, there are some situations that warrant repeating information from their help in our product’s help, such as when configuring their product a certain way will make our product not talk to their product. But they have their own technical writers who have worked hard to make their help available to you at publicly available links, so you should use it.

Why can I never find anything in the help?
Let me state this as kindly as possible: you don’t know how to search. Before computers, searching talent was reserved for librarians, and we counted on them to find things for us. (Inside every good technical writer is the heart of a librarian.) Now we count on Google to find things for us. Sadly, Google has not penetrated every database in the world—yet—so until they do, we must use our own search skills to find the information we need. And, yes, it can be a challenge at times. If you have honestly searched every possible search word you can think of to find what you want (e.g., script, bat, VB, batch…) and still can’t find what you need, send an email to the technical writer of that Help documentation or the product’s user forum and say “I searched for “X” in the help using these terms ‘blah, blah, blah’ and couldn’t find it.” Then I can add those key words to the relevant topics so that next time you will be able to find the right topic. Another point: the application’s Help is written for the average user of that product. If you can truly “never find anything” then perhaps you are an advanced user and should instead search the knowledgebase or user forum, or call technical support?

How can I read the help before I install, if installing the product installs the help file?
GOOD question! I’ve been asking product managers that for years. Well actually what I ask is, why do I need to include installation instructions when no one reads them until after they install, if ever? In my case, the installation Help files are also publicly available online, so you can, if you were so inclined, read the installation instructions online before you install the product. (HINT: Put an “install.txt” file with the installer download!) If you pay extra for technical support, I’m sure the company will hold your hand while you install their product and help you avoid any bumps in the road.

There is so much repetition in this help file, it’s ridiculous!
OK, Grandma, calm down. This is called a “help file,” and the reader can jump into the story at any part in the story. In fact, it’s not a story at all. There is no beginning, middle, or end. It’s a collection of “how to” topics, not a novel. So when Mr. Admin is trying to create a user and starts banging his head against his desk because he can’t figure it out on his own, he can click “Help,” search for “how do I create a user?” and then read a topic called “Creating a User.” He doesn’t want to know why to create a user. He doesn’t want to know what happens at the application level when the user is created. He doesn’t want to know where in the database the user is stored. Right now, all he wants to know is, “how do I create the doggone user?”

(And while you’re laughing because I formatted a sentence in the help with red, bold text, know that I did that because when it was regular, black text, no one would read it. They would scan right past it. I have yet to make it blink, however.)


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.