Re: giving a toss about documentation

Subject: Re: giving a toss about documentation
From: Bill Swallow <techcommdood -at- gmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 1 Apr 2005 10:03:02 -0500

> Now, what if the other player came with no
> documentation at all? And it is $100 less? Who
> will buy that? No one.

Someone who compares features and wants to save $100 will buy it. I
doubt that type of person is rare. Really this whole VCR analogy isn't

> I would go further and say, usability is at the
> core of the product, and documentation is a
> component of a product's usability (at least
> until such time as product interfaces are
> designed so intuitively as to allow users to find
> database staging tables blindfolded).


> I don't know why we wish to couch the usefulness
> of documentation, which is a part of the
> product's usability in terms of experience and
> exasperation. The instructions don't work; the
> product, as far as the user goes, don't work!

Was someone advocating we couch the usefulness of documentation? I
hadn't seen such a comment.

> Then again, it is important to distinguish
> between products where instructions are provided
> just to fulfill a formal req. and those wherein
> instructions are critical using the product. In
> the first case they are a necessary evil. When
> people bring into question the use of docs, they
> are likely talking of such. Those who worked with
> products and took advantage of docs never say so.

Very true. One of the best bits of "documentation" I ever read was on
some kind of candy bar...

1. Unwrap the candy and throw the wrapper away.
2. Eat the candy.
3. Smile.

One of the worst pieces of documentation I ever read was for a guitar
tuner I beta tested. The tuner has 4 buttons on it. The manual had two
of the buttons swapped, so functionality for one was described for the
other. One feature was ignored in the documentation, completely. To
top it off, there were grammatical errors galore in the doc.

But, the doc was indeed a formality. The buttons were labeled on the
product, and to most guitarists (perhaps all who are experienced
enough to know to tune the instrument regularly and who want to
experiment with tunings) know the terminology for the functionality
enough to use the device without referencing a manual.

> For those who believe in (the usefulness of docs)
> no explanation is necessary; for those who don't
> believe, no amount of academic research is
> adequate.

Right. Usefulness of docs is our concern. We know the drill, know the
argument, know the benefits, etc. If you're trying to impress the
importance to someone who doesn't care, you need to find out what they
care about and cater the argument to that.


Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: The sky is starting to fall again
Next by Author: Re: Acrobat Hand Tool
Previous by Thread: Re: giving a toss about documentation
Next by Thread: Re: giving a toss about documentation

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

Sponsored Ads