Re: Why not do it ourselves? (Was: using 3rd-party books)

[Sandy Harris <sandy -at- storm -dot- ca>]

"Carey Jennifer (Cry)" wrote:
 
>         <<That is, it's one thing to write about how a product works, but
> it's quite another to write about how people actually use it. ...
> 
> That's exactly it!!

Yes, but it is only one aspect of it. We're back to the question of audience.

I think all users should have access to a complete reference on the product,
the equivalent of Unix man pages. We cannot forsee what parts of that they'll
need, and some may never need it, but it should be there as a foundation.

Many users will need external links of some sort.

  If your product implements some standard, your docs should point to the
    standards docs.
  If external constraints are critical -- legal standars for a safety product,
    auditing requirements in an accounting package, ... -- point to them.
  If it is based on some formal model -- e.g. if it is a relational or ER
    database -- point to material on that model, preferably both to the
    formal papers and to an introductory text.
  If it used for some complex task, point to referencs on that ask. e.g.
    Methinks a desktop publishing package should include links to some
    typography and design material.

With those in hand, writing the task-oriented material is much easier.

Note also that task-oriented does not mean only the "for dummies" stuff
oriented to beginners. Some of the most advanced material might be in
task-oriented docs for experts. "Performance tuning for ... applications",
"Single source documenmt management with ...", ...
  
> The thing is, as we move more and more into the
> direction of "usability" and "information design" and delivery, it seems
> that we are learning that maybe we should be writing to "how people actually
> use it" rather than "how the product works".  I guess my main concern would
> be that certain important information not get excluded in the process of
> what could potentially turn into the dumbing down of our manuals, which was
> why I was thinking that the beginner's version would include more of the
> simple stuff while the advanced one would have all the other stuff that more
> sophisticated users would want with little-to-no overlap between the two.
> 
> <<The third party books are written because someone believes that the
> manuals don't fill all needs. Usually, they are right.>>
> 
> <<In order to be truly objective, the bugs, (er, features,) would have to be
> documented together with workarounds.

As I see it, it is essential to document limitations of the product. e.g. my
FreeS/WAN stuff has sections on:

the limitations of the IPsec protocols our product is based on,
http://www.freeswan.org/freeswan_trees/freeswan-1.91/doc/ipsec.html#limitations

which features of those protocols we do and don't implement,
http://www.freeswan.org/freeswan_trees/freeswan-1.91/doc/compat.html#spec

and problems that may arise trying to get FreeS/WAN to talk to other
IPsec implementations:
http://www.freeswan.org/freeswan_trees/freeswan-1.91/doc/interop.html#interop.problem

>> Marketing gets upset when this happens.

As for marketing, some users look for this. Especially for security products,
I am impressed by marketing material that is clear on the limitations of what
the product offers. I certainly would neither buy nor recommend to a client
any product whose marketing material appeared to be trying to gloss over
problems, or to make exaggerated claims.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.  http://ieeepcs.org/2001/

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

---
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 
http://www.raycomm.com/techwhirl/ for more resources and info.