RE: "Two-track" documentation

[Bill Burns <BillDB -at- intl -dot- com>]

Honestly, I tried to stay out of this, but I just   can't     control
myself...

I think the issue of accuracy is not so much whether or not the information
is "correct" but whether it's correct given a specific frame of reference. A
description of an action or event may very well be correct to a user given
that frame of reference but incorrect to an engineer who sees that same
event from another frame of reference. It may also be more or less accurate
dependning on what kinds of metaphors might be used  in a context. Yeah, I
know we're supposed to use metaphors, but they're rampant in the software
world (he said clearing the files off of his desktop).

Here's some anecdotal evidence (obviously not valid in a court of logic, but
it'll suffice here). I once documented an application that allowed users to
annotate and alter images (as well as lots of other irrelevant stuff). The
developer used the standard magnifying glass image with the plus and minus
signs to allow users to increase the image size in the display window. An
integration person who happened to be looking over the file took issue with
the way I described the feature. (I think I wrote something to the effect
that the tool "increases the size of the image in the viewing area" or
something of that sort. Yeah, it could be different, but that's not the
point.) She said, "It doesn't increase the size of the image."  

She went on to explain that the tool changes the pixel depth and dimension
of the image as it is displayed but doesn't change the size of the image and
that the algorithm used to do this blah blah. Technically she might have
been correct given her frame of reference (that the image file itself was
not changed, just its appearance and size in the viewing window). But that
wasn't going to help a user who just want to make the image look bigger so
they could view one part of the image better. To the user, the image got
bigger when they clicked it with the Zoom In tool. I couldn't get the point
across until I resorted to the metaphor at use in the application--a
magnifying glass makes the image look bigger.

This goes back to what both Arlen and and Mark B. were saying (and Sue G.
says close to the same thing). This isn't an either/or proposition. Both
accuracy and audience focus are important, and they play off each other. 

'K. I'm done.

Bill  Burns - Eccentric Technology Consultant
INT'L.com Design & Development
billdb -at- intl -dot- com
Y2K Complacent