Re. Online help/docs

Subject: Re. Online help/docs
From: geoff-h -at- MTL -dot- FERIC -dot- CA
Date: Tue, 30 Jan 1996 08:17:38 -0600

Let's back up a step or two: why do we provide docs
(documentation) in the first place? There's only one
reason, with myriad variations on that theme: we document
to answer the questions of our audience because we're not
there to answer the questions in person. The online versus
paper issue is secondary to the main issue of audience: do
we know what our audience will need to know, have we
provided this information, and have we structured the
information so they can find what they need efficiently?

We can't resolve the comprehensive ("put everything online"
or "send 1000 pages of manual") versus simplistic ("context
sensitive help only" or "provide only installation and
tutorial manuals") debate until we define our purpose in
terms of the audience. Different needs require different
solutions: a "fill in the blanks" application form may
require nothing more than a popup list of alternatives for
each blank and a title that states "click in each blank
with the mouse and pick an alternative from the menu that
appears"; desktop publishing software requires a complete
reference, with details on all aspects of the software and
(ideally) a conceptual framework that show you how to link
it all together to produce books. The full range of
possibilities between these extremes may be possible.

In general, you can't avoid comprehensive docs, because
readers always have more questions than simplistic
documentation can answer; if you believe that you're
writing to answer their questions, you can't avoid
producing comprehensive docs. Nonetheless, you don't need
to beat the experts over the head with the details. The
traditional two-tier strategy seems robust to me: provide a
simplified outline for those who already know the answers
but need to refresh their memory, and provide access to
more comprehensive information for those who need it.

The business about the disappointing docs for recent
Microsoft products misses the point: if you buy the
third-party books, you end up with comprehensive docs
anyway. The issue is who provides them; ethically (on
behalf of the audience) and personally (on behalf of my
battered budget), I prefer an approach that provides the
whole package, software and docs, in one box. No hidden
costs, and I don't need to go elsewhere if the docs are
well enough written for me to figure them out.

--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

Disclaimer: If I didn't commit it in print in one of our
reports, it don't represent FERIC's opinion.


Previous by Author: 7 plus or minus 2: followup
Next by Author: Acrobat files
Previous by Thread: 7 plus or minus 2: followup
Next by Thread: Re: Re. Online help/docs


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


Sponsored Ads