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.
> 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?
Well, we were talking about "best", not just "good". Many things can be
good. Only one can be best. We don't usually apply the term best to ordiary
things that do ordinary jobs well. We save "best" for the extraordinary.
I can balanace my checkbook with perfect accuracy (at least, let's pretend I
can). This does not make me the best mathematician or the best accountant.
I can walk to the grocery store without getting winded. This does not make
me the best athlete.
I can toss a ball back and forth from one hand to the other without dropping
it. That does not make me the best juggler.
Perfect performance of easy tasks is not the mark of greatness.
> 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?
No. It has a chance to be as good as it needs to be. But the task is not
difficult enough for even perfect execution to merit the description "best
documentation". You might as well proclaim yourself the "best climber" for
walking up a flight of stairs.
More to the point than a mere argument about the meaning of the word "best"
is this. Holding up solutions to easy problems as exemplars of the craft
does nothing to advance the art or to help anyone progress in it. The
solutions that are worth our attention and study, as well as our praise, as
the solutions to hard problems.
Every time I go to a conference there seems to be somebody giving a speech
on how all documentation can be replaced by pictures. Inevitably, the
examples are documenting simple physical assembly. So what? We all know that
drawings are the best way to document simple physical assembly. They don't
work well for much else, except as supplements to text.
The phonetic alphabet was one of the greatest advances in the history of
mankind. If pictures were a universally applicable means of communication,
we would still be using hieroglyphics.
