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