One idea that’s been crashing through the tech comm world as of late is that people definitely don’t read documentation. While I think that it’s something that we’ve all suspected, it took Joel Spolsky to actually say it.

The reactions to this have been … well, interesting to say the least. My favourite came in a blog post by my friend Tom Johnson. While I don’t agree with everything that Tom wrote in that post, full marks to him for having the courage to call the situation as he saw it and offer a very contrarian point of view.

Still, this is a problem. And one that we have to address sooner rather than later. Here are a few thoughts.

The manual is dead

For the last couple of years, Aaron and I have been pushing the idea that the manual as we know it is at the end of its usefulness seems to be gaining traction. By manual as we know it, I mean a guide that’s a systematic walk through the features and functions of an application or a device.

Obviously, that’s not enough even when the user is a newbie. At all stages of mastery, user want and need not just the basics but advanced topics. They want to know how to get things done in the quickest and most efficient way.

Looking elsewhere

How do people get information about what they’re using? Do they press F1 or do they turn to Google? In a very unscientific survey that I conducted, everyone I asked said they go to a search engine first and then turn to the official documentation. And not always the latter. Welcome to the cottage industry of supplementary documentation.

I think that’s a key to making documentation more palatable and useful. Make documentation more like the information that users are finding on the Web. Focus on specific tasks, not features. Task-based documentation, but to the extreme.

If you analyze the supplementary documentation that’s out there — whether in forum posts, on blogs, or in wikis — you’ll notice that it:

  1. Often covers information that isn’t in the official documentation (obviously!)
  2. Generally tackles questions or problems that a number of users encounter
  3. Is usually presented in a very conversational, easy-to-read format

Those points aren’t always the norm, but they’re not unheard of either.

It might be time to ditch the whole idea of the manual. Dump the tree-like table of contents. Forget the systematic, linear walkthrough. And instead:

  • Focus on procedures
  • Group procedures by type — for example, How do I export …
  • Shunt overview, expository, and introductory information elsewhere. But make sure that there are links to that information
  • Write in a more relaxed, conversational manner
  • Hyperlink extensively where needed
  • If the documentation is on the Web, use techniques of SEO to ensure that your documentation appears at or near the top of searches

Obviously, you’re not going to be able to cover, or even come up with, all the scenarios that users might encounter. That’s where the community comes in.

Work with the community

Technical writers can be … well, control freaks. We don’t like other people messing about with our documentation. Something that we need to remember, though, is that it isn’t our documentation. We’re not writing it for ourselves. We’re writing it for the people using the software and hardware that we’re documenting. And, as I keep saying, the insights of users are just as valuable as our own.

Sometimes, even more so. Why? They’re using those apps and gadgets in ways that we can’t imagine in our little development silos. Why not tap that expertise? Encourage users to contribute to your documentation through such outlets as wikis or forums. It will be a little extra work to incorporate user-generated content into your documentation — it involves more than just copying and pasting. You’ll need to do some editing and reformatting, as well as some gardening. And then there are licensing and copyright issues, as well as issues of compensation.

If you need some pointers on working with the community, you should definitely read Anne Gentle‘s excellent book Conversation and Community: The Social Web for Documentation.

Change is gonna come

Sooner rather than later. To remain relevant, technical communicators will have to change the way in which they view, create, and deliver documentation. We’re no longer the fount of all knowledge. We’re a source of information, a filter, and a funnel. But by embracing those roles, it’s possible to create documentation that users will read.

The documentation we’ll be producing in years to come probably won’t look like the documentation that we’ve been used to. And there’s nothing wrong with that. You don’t kill something by changing it. The change will happen, whether we act or not. Why not have a hand in the change instead of sitting idly by and letting it happy slap us?

Thoughts? As always, feel free to leave a comment.

Photo credit: gracey from morguefile.com

  • Share/Bookmark

Related posts:

  1. Giving users incentives to contribute to the documentation
  2. Musings on user-generated documentation
  3. A thought to apply to documentation, and users

Related Posts