Documenting a buggy feature (was: RE: techwr-l digest: April 30, 2002)

["Dan Hall" <dhall -at- san-carlos -dot- rms -dot- slb -dot- com>]

Patty,

In an ideal world... ;-)

Development shouldn't be releasing buggy software. So, you
should be able to document how a feature _should_ work, and
then the docs will match the software once they fix the
bugs. <sardonic laughter>

This being reality, IMO the documentation needs to reflect
the actual working of the product. That means you need to
decide (or to work with management to decide) how you are
going to handle features that are included but not yet
"fully functional".

This might mean that some features are undocumented, or
that the documentation contains caveats, or it might mean
that your docs have the appropriate work-arounds to get the
product to do what it's supposed to. None of these is the
"correct" solution (which is to make the product work
right), but any of them will work as an alternate. I'd
suggest that it's a management decision on how to handle
this problem - it's not really up to the writers.

If you can show management that the "broken" features are
key to the software's success, it might mean that
development gets a kick in the seat-of-the-pants to fix
the bugs. But don't count on it. Most likely, you'll have
to work around them.

My personal preference is to leave "broken" features out
of the documentation - though if they are reflected in the
interface this is more difficult. Releasing software that's
buggy is _not_ a good way to get or keep customers (though
it seems to be working for Microsoft). I'd prefer that all
the "official" features work correctly. If documented
features don't work, the customer thinks they've been
cheated, whereas if there are undocumented "extras", they
seem like a benefit.

Or, if you report to marketing, you may just have to
document the broken features as if they work. <g>

HTH

Dan

It is the mark of an educated mind to rest satisfied with the
degree of precision which the nature of the subject admits and
not to seek exactness where only an approximation is possible.

- Aristotle


-----Original Message-----
From: bounce-techwr-l-72045 -at- lists -dot- raycomm -dot- com
[mailto:bounce-techwr-l-72045 -at- lists -dot- raycomm -dot- com]On Behalf Of Blount,
Patricia
Sent: Wednesday, May 01, 2002 9:10 AM
To: TECHWR-L
Subject: RE: techwr-l digest: April 30, 2002



Hi,

I need the benefit of your collective experiences... as tech writers, we
frequently are documenting products that are still under development, so
that the documents can ship with the product, no?

OK, so what have you done when faced with a feature that is at best,
"buggy". Sometimes it works, sometimes it doesn't.  If you write a procedure
according to the way it's supposed to work (i.e., design intention), then
your book is wrong at least part  of the time.

I'm wondering if the books should contain an alternative section, something
like "What to do if this procedure fails to produce the desired result..."

Any suggestions?

Thanks,

patty


******************************************************
Patricia A. Blount
CA Education
Supervisor: Technical Writing
Computer Associates International, Inc.
One Computer Associates Plaza
Islandia, NY, 11749
+1 631 342- 3528
fax +1 631 851-8534
patricia -dot- blount -at- ca -dot- com



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

---
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.