RE: Best Documentation

[Brent L Jones <brent -dot- jones -at- jadesolutions -dot- com>]

Mark Baker wrote on 28 January 2000 07:49:

> The only problem with calling this "best documentation" is 
> that it does not
> solve a particularly hard problem. It just shows how to fit 
> pieces together.
> Sure, pictures work fine for this. Ikea's documentation 
> generally works well
> for the same reason. But there are no concepts to be mastered 
> here. There
> are no conditions to assess. No interactions with an external 
> environment to
> manage. Not even any tools required. Physical assembly of 
> well designed
> components just isn't much of a challenge to do or to document.
> 
> "Best documentation" should be saved for documentation that 
> solves a harder
> problem.

Hmmmmmm. This is interesting. So no matter how effective, elegant, and
useful a piece of documentation is, then it's not really "good" unless it's
difficult to write? Unless writing it involves wrestling w/ Byzantine
concepts and arcane interactions?

So if I'm documenting a very well-designed system w/ a GUI that is
incredibly intuitive, then my documentation has no chance at all to be the
best? Just because the system is well-designed and easy to use? Just because
I don't have to sweat bullets to make it comprehensible?

I disagree. And I also challenge your assertion that this sort of
documentation is easy to do. I've never done it, but I've thought about it,
and I suspect that that simple elegance comes at the expense of a lot of
time and thought. I don't think it's a trivial task. Have you ever tried to
put something together w/ poorly written instructions? If it's such a
trivial task to produce assembly docs, why are so many of them so bad?

It's very easy to sneer at someone else's accomplishments and say "Oh,
that's easy." You know, people say that about technical writing *in general*
all the time--that is, until they actually have to sit down and do it.

"Best documentation" should be saved for documentation that meets the needs
of its users in an efficient, elegant, usable way.

cheers,
brent

--
Brent Jones, Documentation Manager
bjones -at- JadeSolutions -dot- com
JADE Solutions
Office: 303 448 1019 x 40
FAX: 303 449 1548