Re: Errata coverage

["Parks, Beverly" <ParksB -at- EMH1 -dot- HQISEC -dot- ARMY -dot- MIL>]

I have to go with the majority in this case. Based on the example you
gave, I know the kinds of "errors" you are talking about. They are not
technically errors, just poor attention to detail combined with the
programmers not having time or not thinking them important enough to fix
before the product is released. I see this, as well, in our product
(which is an internal product, not a retail product). This may also be a
sign of an inadequate testing process.

Highlighting this sort of thing in the manual serves only to point out
the shortfalls in the development/testing process. It would be like
giving yourselves a bad review. I would put these things in the release
notes where the purpose is more "yes, we know this problem exists and we
intend to fix it."

This is my opinion and comes from being on both sides of this situation
(developer and documenter).

Bev Parks
parksb -at- emh1 -dot- hqisec -dot- army -dot- mil
The Friendly Faces of TECHWR-L -
http://www.bayside.net/users/cbsites/techwr-l/


>----------
>From:  Mac McCartt[SMTP:mmccartt -at- AUTOIII -dot- COM]
>Sent:  Wednesday, October 08, 1997 8:24 AM
>To:    TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>Subject:       Errata coverage
>
>I find myself in a position where what I want to do is opposed by nearly
>everybody else who has expressed an opinion. Maybe the writers on this list
>can share their opinions on this subject with me as well.
>
>The point of contention is about how to cover idiosyncrasies of the
>software product for which I write manuals.
>
>My view is that I should document these non-critical "errors" in the heart
>of the manual (a sample error is one in which a dialog box is displayed
>improperly, not showing all of the two buttons that reside at the bottom of
>the dialog box). My contention is that, unless covered in the manual, the
>idiosyncrasies are in danger of becoming "hidden" -- and therefore
>potentially confusing for the user.
>
>The opposing view is that coverage of this kind of error belongs in the
>release notes, not in the manual. Covering this error in the manual (the
>opposition goes on to say), "enshrines" it -- and needlessly complicates my
>(the writer's) life. It would seem that this view presupposes that release
>notes are read religiously (or more religiously than the manual, at any
>rate).
>
>What do you think?
>

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html