TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:RE: Best Documentation From:Brent L Jones <brent -dot- jones -at- jadesolutions -dot- com> To:"'Mark Baker'" <mbaker -at- omnimark -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 28 Jan 2000 09:42:32 -0700
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
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.