Using 3rd-party books?

Subject: Using 3rd-party books?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 19 Sep 2001 08:47:35 -0400

Matthew Horn's company produces <<...a Web application server. It conforms
to industry standards and therefor our customers who write applications must
follow these standards. When writing applications that run on our server
they can
currently use our books which describe not only how to use our product, but
also how to write these applications. However, there are many books that
cover in-depth how to write applications.>>

Since the goal of documentation is to help people use your product, it makes
good sense to include a bibliography of books that cover your subject in
some depth. Advanced users will greatly appreciate knowing that they have
other places to go for specific documentation issues that are beyond the
scope of your own docs.

<<So my doc manager had an interesting idea... why not include third-party
books that cover the basics of application development so we, the writers,
can concentrate on the more specific discussions of our product?>>

The danger in doing that is that eventually all you writers could be
replaced by <g>. Worse yet, bundling other people's manuals with
your product could lead your managers to hire the authors of those manuals
as contractors and show you the door. Tread carefully here unless you want
to propose this, downsize yourself, and become one of those third-party
authors! My suspicion is that your manager has got the story backwards: you
should be writing documentation that lets readers accomplish all the basic
tasks they'd want to accomplish with a product, and leave the advanced works
to other authors. That's certainly the traditional approach, and it makes
great sense to me as a user of commercial products: when I receive the
product, I don't want to have to go to the bookstore to use it, but I do
want to know that advanced works are available once I've mastered the basics
and want to learn more.

--Geoff Hart, FERIC
580 boul. St-Jean, Pointe-Claire, Quebec H9R 3J9
geoff-h -at- mtl -dot- feric -dot- ca


A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.

+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: +++

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Cross-references with numbered headings?
Next by Author: '97 PowerPoint problem and question?
Previous by Thread: Cross-references with numbered headings?
Next by Thread: '97 PowerPoint problem and question?

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

Sponsored Ads