Wednesday, February 04, 2009

Description is Not Documentation

We're in the business of documentation. You. Me. All of us. We read documentation better than the average citizen, and I hope we write better documentation than the average citizen.

It seems odd to say we're in the business of reading documentation, but that's a big part of what we do.

One time I had a client call me with a simple sounding problem. She had a new piece of software and couldn't figure out a very basic function. I explained to her that it was probably extremely easy, but someone has to read the documentation. I said:

"Either you can read the four-page instructions or I can. Would you like me to read the instructions for you?"

And she said, "Oh, yeah. That would be great."

I was trying to be a smart-ass. But it turns out that it was exactly what the client wanted. She's not in the software business or the technology business. She's an insurance broker. Her most profitable activity is NOT reading documentation. She pays someone to do that.

:-)

[Important lesson: If you're NOT doing managed services, you want as many of these clients as possible. If they'll pay you to change toner cartridges at $120/hour, do it.]

But we're the same way: When a fat document from the IRS shows up, I hand it to the accountant and ask him to read it for me. My high value time is spent elsewhere.

I've heard consultants say that they don't want clients to see them reading instructions online or looking up help on Technet. Why not? Can your clients find anything on Technet? Most technicians can't!

Hand a client a Technet CD and a foreign language textbook: They won't understand either one. But they'll open the textbook.

You're in the business of reading documentation and turning words into actions.

Poorly Written Documentation

I can't count how many programs my business uses on a regular basis, but it's a lot. Office products, development products, LOB Apps, financial packages, CRM systems, operating systems, etc.

A lot.

One of the things that stands out among top-shelf products (Microsoft, Adobe, QuickBooks) is that they are extremely well documented.

As you move down the spectrum to home-made products and products essentially written by one person and released into the wild, you see products with NO documentation. Luckily, we don't see many of these.

Unfortunately, we DO SEE a lot of products that are a notch up from that. They are expensive, widely distributed, and horribly documented.

Most of these products are extremely feature-rich. But you wouldn't know that by reading their documentation.

The biggest mistake these companies make with documentation is that they only describe the product. They literally start with the File menu and tell you what each option does.

    The NEW command opens a new document.
    The OPEN command opens an existing document.
    The RENAME FILE command renames the file.
    The PRINT PREVIEW command previews what the document will look like when printed.


No Sh!T.

And they're proud of their documentation! "We have a 97 page help file, RoboHelp, etc."

    The LOAD MACRO command loads a macro.
    The RECORD MACRO command records a macro.
    The EDIT MACRO command edits a macro.

Duh.

Description is not documentation.

While the description of features is useful and necessary, it is simply a precursor to the real documentation.

Documentation should help someone sit down and USE a program. Think about it. When do you reach for the documentation? It's NOT when you want to find out every command on every menu. You can do that by selecting each menu and reading them.

You reach for documentation when you want to find out how to do something.

How do I import . . . ?
How do I format . . . ?
How do I run a report . . . ?
etc.

At KPEnterprises (Sacramento's Premier Microsoft Small Business Specialist), we take a lot of pride in our documentation. Some of it is simply filling out forms.

But the documentation that matters is the documentation of processes. The "How Do I" documentation.

We create customized documentation for clients, sometimes on the simplest processes. When we're done, the client can hire a new person, show them once, and hand over a task to the newly trained employee.

The goal here is to shove the E-Myth into every organization we find.

:-)

No comments:

Post a Comment

Feedback Welcome

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

Disagreements welcome!