Monday, August 04, 2008

Documentation is Hard

I admit it: Documentation is hard.

I used to think it was easy. Only over time have I come to realize how hard it is.

My experience with documentation came from instructing others, not from documenting a process. I did document a process, but completely from the view of an end user.

The difference is dramatic, and sometimes difficult for programmers to understand.

I thought documentation was easy because I always did it from the user's perspective.

The first documentation I wrote was for an online information service (back when online meant modem dial-up. There was no world wide web.).

I had to document everything my employees needed to do to gather information, enter it into the computers, generate reports, and verify the data. In many cases, they did not understand what they were doing. But if they followed the steps exactly as outlined, they were perfectly successful.

In the last year I have invested in two major programs that cost hundreds of dollars each. Each has a massive amount of "documentation," but that documentation is essentially worthless to people who did not write the program.

This documentation was obviously written by developers.

There's something screwy about the modern programming era. Many people assume that anything with a graphical interface doesn't need documentation. I hope we all know that's not true.

There are primarily two types of bad documentation:

1) Type A Bad is the worst documentation. It focuses completely on a series of very specific functions and assumes complete knowledge of everything else.

2) Type B Bad is the second worst documentation. It describes every drop-down menu option without any really useful information.

For example:

On the Format menu . . .
- Reformat Paragraph opens a dialog box in which you can reformat a paragraph.
- Paragraph Formatting allows you to format a paragraph.
- Convert CR/LF to Wrap converts carriage return/line feeds to Wrap.
- Trim Trailing Spaces trims spaces for the end of lines.


No Kidding, Sherlock.

The problem with the Type A Bad documentation is that the writers are completely accurate, but don't give the user any context. They say "Select MAIN and choose the CPX function." But they don't give you a start page, a link, etc.

Main what? From where? Where do I start?

This documentation is written under the philosophy called PCIPU: Perfectly Clear If Previously Understood. If you know the software but haven't used a specific function, this documentation is great. But before you're an expert, it's almost useless.

The biggest solution for Type A Bad documentation is a really good Start Here section.

    OK, you got this thing installed. Now what do you do?

    "Start by creating categories and users. To create categories, go to the Options page and click . . .."


Once documentation is placed inside the context of meaningful tasks, people will find it very useful. After all, software is created in order to accomplish something. The user bought it for a purpose and seeks documentation in order to achieve that purpose.

Type B Bad documentation is also accurate, but almost never useful. If you can read the menu, you don't need this level of documentation.

The solution for Type B Bad documentation is to step back a layer and create more general topics. So, let the topic be formatting, and include the details within that. Don't repeat the menus, but simply state what's on them. Then, give hints, tips, examples, and hot-keys.

The overall problem with bad documentation is that it does not address the needs of the end user sitting down to do something for the first time.

Most of the time, most people using most software are task oriented. How do I create new users? How do I assign them to categories?

In addition to the basic skeleton of using the functions, documentation should focus on how to achieve things with the software. That's why examples and additional tips are valuable.

It is no surprise that the best selling software in the world (Microsoft's Office, Adobe CS3, etc.) have extremely good documentation. In addition to meaningful descriptions, the documentation is filled with examples.

- - - - -

One final type of bad documentation is a distant third, but worth noting: Video-only documentation.

If you like to learn from videos, then having them available is great. But video should always be a supplement to real documentation. Videos are not random access. They require a certain level of commitment from the viewer, which may not be available at the time documentation is needed.

You provide 600 hours of training videos? Great. After I'm done reading your documentation, I might access some of those videos. But I don't have 600 hours to come up to speed on your product.

- - - - -

The reality is: Almost no one reads all the documentation available. Most people read what they need, when they need it.

And what do they want to do immediately?

99% of the time, they want to complete a function. Create users. Add them to categories. And so forth.

I encourage you to participate in documentation feedback programs when asked.

Writing documentation is hard. In some ways, it's like editing your own writing. You know what you meant to write, so you see that every time you read it. Someone else needs to read your writing in order to give you accurate feedback.

And that someone needs to be completely honest.

No comments:

Post a Comment

Feedback Welcome

Please note, however, that spam will be deleted, as will abusive posts.

Disagreements welcome!