Stop Creating BAD Documentation!

 I prefer learning from the written word. But I often to turn to video as well. But time and time again, I realize that I'm just not getting what I need - because the "how to" is horrible. Each of these formats has a primary problem, although it manifests differently. And the primary problem has an ironic cause.

Documentation is ultimately just a specific kind for communication. The primary function of all communication is to transfer information (or opinion). The factors that define successful communication are clarity and brevity. Unlike fiction or even commentary, documentation requires clarity and brevity. No one wants an 800-page novel about how to set up a remote access to a storage device.

The Primary Problem

The biggest mistake people make is to skip steps. And the most important step that gets skipped is usually the first step. If you keep any eye out for it, you'll see it again and again. The documentation assumes that you're logged in to the program you want and you have the correct page or document open.

This is because the person the person writing the document is 1) very knowledgeable, and 2) in a hurry. You'll notice this, in a written document, when you ask yourself, "Where am I supposed to be and how did I get there?" For example, if a document begins:

"From the FILE menu, select the folder ..."

Wait. What? Which file menu?

I know it seems simplistic, but the ultimate GOAL of documentation in the long run is to save time and money by handing the documentation to someone who is competent and let them execute it. To do this, they need to know exactly where they start and then go click-by-click.

In video tutorials, you'll see that someone clicks through a lot of stuff while they're talking about something else or doing the introduction. So you see them click on a project folder, right-click, open a document, go to the dashboard, select and option ... And then the dialog and visual are in sync. 

In this case, you find yourself rewinding 30 seconds again and again in order to figure out what they did zip-zip-zip as second nature. The video "watch time" is through the roof because you keep watching a tiny portion of it over and over. At this point, you should realized that you need to look elsewhere. If you can't get past the first minute without rewinding five times, the rest of the video will be torture.

The Irony is that documentation is supposed to save you time in the long run. But if the documentation is poorly written or poorly demonstrated, it wastes a great deal of time. Documentation is the ultimate example of: Take time to do it right!

It's also a great example of one of the absolutely unbreakable rules of service delivery - Slow Down, Get More Done. A little extra time spend on documentation will save massive amounts of time down the road.

Comments welcome.

:-)