Re: [gtk-list] Re: Documentation



On Thu, 20 Jan 2000 11:11:50 +0100, Guillaume Laurent <glaurent@worldnet.fr>  said:
> The only way documentation is going to get written is if people who
> wrote the code document it, or at the very least clearly explain it to 
> a technical writer.

A very good point.  Writing good usable documentation is a skill.
Not everybody has this skill nor the training to do it well.
I spent 2 years part-time doing help desk, and 6 months full time
writing documentation, and was glad to get into programming, it's
a lot easier to do well.

I've seen cases where the "people who wrote the code" documented
it, and I'd rather have been without documentation.  If the user's
manual and the code don't match up, you're left wondering whether
the programmer botched the user's manual, or if the user's manual
states what the programmer MEANT the code to do and you've found
a bug.

Note that documentation *inside* the program (comments and so on)
is another issue entirely. I've met plenty of programmers (including
myself) who comment well, and another programmer trying to fix the
code has an easy time - but who can't write a decent user's guide
due to a mindset problem.  Heck, *I* can see how obvious it is
what ways you could use widget XYZ - explaining the possible uses
to somebody who Just Doesn't Get It Yet is a challenge. ;)

The single biggest challenge for programmers writing documentation
is *ignoring* their knowledge base.  All those things that you
just *know* are true because you've had your head stuck inside the
code for the last 2 months?  Well.. if somebody is reading the user's
guide, they don't know all that stuff.

The hassle is, of course, that there is just as big a shortage of
qualified technical writers as there is of programmers.  However,
the open-source movement has benefitted from the fact that many
programmers are willing to forego sleep to Write Code.

Not many technical writers feel the urge to get up at 3AM and Write Manuals.
The ones that get up at 3AM are probably Writing The Great American Novel. ;)

And that's why good manuals are so hard to come by.

				Valdis Kletnieks
				Operating Systems Analyst
				Virginia Tech



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]