bug#10072: 23.3; invisible text

["Drew Adams" <drew.adams@oracle.com>]

> > Fundamentally it's a bug, and I generally don't like to 
> > document bugs.
> 
> On this point I disagree with you very strongly.  It's much /more/
> important to document bugs than any other aspect of the code.  I have
> told several students this from time to time, and, like you, they
> tend to resist the idea.
> 
> I gather that there is no great push on to remedy this behavior,
> so this bug may hang around for some time . . .

FWIW - Bugs, other known problems, and workarounds are typically *not*
documented as part of the technical doc itself.  One reason for this is that the
doc is meant to describe what the product does, or rather, what it should do,
what it is supposed to do.  In a way, the doc is like a spec that the product is
meant to reflect.

Selected bugs and workarounds are, however, often documented in accessory,
release-specific documents such as release notes and readmes.  One of the main
purposes of release notes and such is to let users know about certain known
problems and limitations, and how they might work around them.

And of course bugs are also often documented (after a fashion) in a bug tracking
system.  For user-visible bugs, that gives users a sense of the history and fix
progress.