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.
Karen
kwg -at- datatel -dot- com
--------------------Original Posting------------------------------------
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.
