Unless you’ve been living in a cave over the last couple of years, you’ve no doubt realized that the the ideas and concepts of Web 2.0 (I hate that term, don’t you?) have leached into the world of documentation. Online help and manuals still exist, but they’re now supplemented product blogs, wikis, and user-generated documentation in forums and on the wikis.

All of this seems like a great boon to the technical communicator. Once the documentation for a release has been finalized and locked down (as a help system or a PDF, for example), wikis and forums and blogs and podcasts can be used for updates and errata, as well as to present real-world scenarios, troubleshooting tips, and any other information that might not fit comfortably in the mainline documentation.

A number of companies of many sizes have thriving user communities and developer/product blogs — two good examples of this are MySQL and Splunk. Of course, the users of and contributors to this type of documentation are usually quite tech- and Web-savvy.

What about everyone else?

But as Tom Johnson points out, not everyone uses or even knows about whatever supplementary documentation you have. Tom stated something that I found very interesting:

I learned that if the help material isn’t in the online help file, it doesn’t exist. So what if you have a separate user wiki, or a product blog, or a user forum. If it’s not intimately integrated into your online help — in fact, if it’s not included in the right book on the right topic in the help, where all other information about that topic is grouped — you might as well delete it. Don’t even bother with it. Users assume all relevant help information is in the help file, and not somewhere else.

The point here is that some users aren’t as savvy as others. There’s nothing wrong with that, but you will have to cater to both groups. And everyone in between. The problem is trying to find a balance.

Grouping and chunking

Tom makes a case for including all of the supplementary documentation — be it PDF user guides, quick reference cards, slides, diagrams, or screencasts — in a separate topic in an online help system. As Tom writes:

Help is more useful if all topics (including user forum nuggets, knowledge base articles, or support call logs) are grouped by topic in the online help.

This, of course, will result in a larger help system. But it will be a more complete help system.

What about linking?

Linking seems like a logical and easy answer. But is this the way in which users will actually want to access documentation? Or are you just adding an additional layer of complexity to the process?

Take, for example, linking to a forum. This isn’t always the best answer. You might be able to link to a specific topic, but the location of that topic might change. Linking to the forum itself is all-but-useless. If you’ve ever used a forum’s search feature, you know how many irrelevant hits that you have to claw through before you find what you’re looking for. Assuming that you ever do find it. Most users, who need answers quickly, won’t have the time or patience root through search results.

Managing all of this information

A lot of supplementary documentation can be useful, and much of it can be a good fit in the user documentation. But the problem becomes how to manage and merge it with the documentation. Tom suggests updating the help regularly. This is a viable solution in his case — Tom’s help is served off of a SharePoint portal. Updates can be seamless.

On the other hand, if you’re bundling help with an application doing regular updates isn’t as easy. There is no guarantee that users will update their help even if they know that an update is available. The same goes for a guide in PDF format.

This is definitely a case in which knowing your audience comes in handy. If you know that a majority of your users won’t know about the supplementary documentation, then it might be useful to include a section in the online help and user guide that points to a wiki or a blog or a knowledge base. More knowledgeable users are apt to know that you have supplementary documentation on your Web site. But don’t take that as a given. As my colleague Keith Soltys pointed out: “I ran into a similar situation recently, when I suggested to a developer that we use a wiki for some of his documentation. He didn’t know what a wiki was. In that case, it was obviously time to step back and go with something a bit less bleeding edge.”

There is no solution that will suit all users, though. All you can do is go back to basics, analyze and survey your audience, and try to come up with the best way to deliver documentation to them.

Related posts:

1. Musings on user-generated documentation
2. Wikis for supplementary documentation
3. Getting users to read the documentation