The Abstract Truth

How to Write Crappy Documentation

Posted by rbpasker on March 10, 2008

Dear Documentation Author:

Thank for putting out a 150 page document on your new product. I really appreciate it when a company puts the time and effort into producing a voluminous manual, rather than just letting people figure it out for themselves.

But I would have to say, your documentation is worse than useless.

Here is a perfect example:


It is not OK to show a screenshot of a dialog box and then just list the elements in the dialog box and tell me to fill it in!

You also don’t need to tell me how to mark a checkbox, “Click next” or “Click Finish”.

I do in fact know how to read the screen, and I do in fact know how to use a mouse and keyboard to move around the screen and fill in boxes.

What I don’t know and can’t tell from your documentation, is the definition and usage of concepts and terms in the dialog box, such as “Server Path Mapping”, “Platform Server”, and “Platform GUI”. Please either inline or hyperlink descriptions of what they are, and tell me how your application uses this information. I don’t need to know how to go about “Defining a Platform Server”. I need to know what a “Platform Server” is.

Furthermore, you documentation implicitly asks me questions (‘Do I want platform integration?’, “Do I want ‘tunneling’?”), without giving me any clue about how to make a decision or what the impact is of my decision.

It seems that some of the information on the form – URL, return host, server root, username and password – needs to be coordinated with other applications. It would be useful to know exactly where this information comes from, and how its used here.

I’m also concerned about putting a password into the dialog box. Is it stored in plain text? What are the permissions on the file in which they’re stored?

And please don’t tell me to “enter the relevant information.” If I knew the “relevant information,” I wouldn’t be reading the documentation. Its your job to tell me what the relevant information is, where it comes from, and how its used in the application.

I wish that the above was an isolated incident. But in fact, this may be one of the more informative sections of your manual.

The point of documentation is to inform and educate, not to explain how to move around the screen and how to fill in the blanks.

I’m sorry, but your manual just doesn’t cut it.

And its worse than useless because I spent way too much time hunting around for information in your manual, and not enough time getting done what I wanted to do.

A former user

Leave a Reply

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

You are commenting using your 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

%d bloggers like this: