Complete documentation?

Subject: Complete documentation?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: Tracy Taylor <ipsque -at- yahoo -dot- com>, TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 12 Jan 2006 16:04:30 -0500

Tracy Taylor wondered: <<We are lucky in that we get some feedback on our documentation from customers, but I'm not always sure how to address the feedback.>>

Obviously (and I'm not trying to sound patronizing here), you should address the feedback in a way that solves the problem. Of course, you need to understand the feedback before you can do so. For example:

<<For example, we get feedback that we need "complete documentation." In your mind, what does that mean?>>

While I'm flattered that you care about my opinion <g>, it really doesn't matter a tinker's dam what I think in this case. This could mean "give us a 500-page printed manual we can read on the bus instead of that damned online help", provide an online tutorial, or "you forgot to explain half the menu choices". The only person who can tell you what it means is the person who made that comment.

Note that comments may be wrong, but still very revealing. For example, they may not be able to find something because they don't know what search term to use, and understanding what search term they used lets you include it in the index. On the other hand, they may not know that the index exists or how to use the search tool. Each such revelation provides insights into how to fix the problem (often by educating the user).

This means if you've been collecting feedback without some way to find out who submitted the feedback, you need to modify your approach so that you have the chance to contact these people. It's sometimes possible to send out a broadcast "we've been told the documentation is incomplete--what do you think is missing?" message to all your customers, but that's arguably less effective, and it doesn't give you the option of specifically responding to each individual who provided comments.

<<We also get complaints that people can't find information.>>

That's pretty much inevitable, since it's not possible to cover every possible way that people might try to look for things. But again, you need details, not suppositions. Do they mean that your index is too shallow, that you have no index but rely solely on one of those useless search tools, or that you forgot to include a detailed table of contents? Or does it mean that your documentation is incomplete: the index, search tool, and table of contents are perfect, but the information simply isn't present?

<<Accuracy I understand better, but again, it's hard to address how to be more accurate.>>

No, it's not hard at all--but it can be quite time-consuming. Every statement you include in your documentation is either correct (accurate), or it's not. The way you improve accuracy is to test every statement, and fix it when it doesn't match the reality. (Note that you may have to qualify some statements, since accuracy may depend on the context. For example, Word's advanced pattern matching tool works as advertised in Windows, but not on the Mac--though you'd never know that from the Mac documentation.) Test each statement, and if it's correct and all exceptions are clearly reported, then it's accurate.

However, note that many people say "accurate" when they mean "complete". Again, you need to ask the customer to be specific. If they can't define their problem objectively and precisely, then at least they can provide examples that will help you suss out what they're getting at. Enough examples reveal patterns you can work with.

<<What is complete and accurate documentation to you?>>

An impossibility, but one worth striving for? <g> At least if you aim for perfection, you'll end up with a better result after you fail than if you aimed for "barely good enough". The way you get to perfection is by understanding where you've failed and taking appropriate corrective measures.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author content and configure Help in MS Word or any HTML editor. No proprietary editor! *August release.

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

complete documentation: From: Tracy Taylor

Previous by Author: Disappearing Changes?
Next by Author: Examples of good tech writing? (take II)
Previous by Thread: Re: complete documentation
Next by Thread: Re: complete documentation

What this post helpful? Share it with friends and colleagues:

Sponsored Ads