"Know thy audience"; was: RE: What is "well Written"?

[John Posada]

Sorry for the delay in responding...deadlines, ya'know?

anyway...

> It is our function, among other things, to create 
> documentation that makes the discovery of what to 
> seek a straightforward task with a minimum
> of frustrations. (Also why a good index is a godsend, 
> to respond to yet another current thread!)

Documentation makes no discoveries...you need to make your
discoveries and, in my opinion, can only do it WITH documentation by
testing how it is used, examining the results of the tests and making
continual improvements to the documentation based on the tests.

Get five typical users. Present to them a section of a document and
observe if/how they were able to accomplish the goal of the section,
what conent they used, what they didn't. Maybe an index is good...you
don't know until you observe and se that they looked for an
index...if not one of your test subjects looked for one, how useful
would it be?

If they were not able to perform the task, or if they were but with
dificulty/questions/needed hints, address where they were having the
problem, then test five other typical users. Continue this cycle
untill you've reached a satisfactory result, run out of users, run
out of time, or run out of money. At least now you have a better idea
of the appropriate type of documentation, it's depth, how detailed,
how technical, what kind of language, etc. Now make style guide and
templates reflect this investigation, as long as the targeted user is
the same.

John Posada
Senior Technical Writer

"They say everyone needs goals. Mine is to live forever.
So far, so good."