Re: Best Documentation

Subject: Re: Best Documentation
From: "Mark Baker" <mbaker -at- omnimark -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 28 Jan 2000 12:54:29 -0500

Brent L Jones

> This is interesting. So no matter how effective, elegant, and
> useful a piece of documentation is, then it's not really "good" unless
> 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.

RE: Best Documentation: From: Brent L Jones

Previous by Author: Re: Best Documentation
Next by Author: Re: The origins of task-oriented writing as a preference
Previous by Thread: RE: Best Documentation
Next by Thread: RE: Best Documentation

What this post helpful? Share it with friends and colleagues:

Sponsored Ads