Re. Online help/docs

[geoff-h -at- MTL -dot- FERIC -dot- CA]

 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.