[Techtalk] Re: [Grrltalk] Documentation (was: Mandrake/Linux newbie deep in confusion about apache/advx)

[Mary]

On Tue, Oct 22, 2002, Alvin Goats wrote:
> Unfortunately, the developer is also the one who knows the thing best.
> I say thing because this applies to electrical engineers, mechanical
> engineers, process engineers, design engineers, chemists, physicists,
> geologists, programmers, ... the list goes on. 

Depends. You know how to build it and fix it best, but do you know how
to use it as a black box best? Possibly not.

Most users want the program to be black box (ie they don't want to know
about the internals). It's hard to lay aside your inside knowledge when
writing documentation, and remember that just because you used
libfoo-style config files and therefore values are comma-separated, and
order is not important doesn't mean you can put "config files are
standard libfoo" in the documentation.

Because insiders have a jargon they use to understand their field[0],
they have to be very aware of when to abandon their jargon, and they
need be fluent in the alternative jargon of the standard user of their
program.

I've had someone who knows cars inside out try and teach me to drive
better and it was excruciating, because every helpful tip was
*preceeded* by an explanation of what I was doing to the clutch plate
using my current technique. I needed it explained in terms of the gear
stick and the clutch, because that's how I interact with cars, not in
terms of the drive shaft and clutch plate, which is how he interacts
with cars.

-Mary

[0] Not a bad thing. If it takes one jargon word for you to convey
something to a fellow electrical engineer, versus perhaps fifty words in
standard English, of course you use jargon, it's how humans get jobs
done.