temporary bug "fixes" in documentation (i.e., workarounds and kludges)

Bugs come and bugs go... Bugs come in various forms; some stay for a very brief time before they get fixed; others never get fixed.

Writers of documentation often include kludges to work around some bugs due to inadequate development of the software applications. No problem there, except... except when such kludges are not disclosed appropriately. When editing the Writer Guide starting in 2006, I might come across on occasion some esoteric empty paragraphs or extra spaces and some such in templates, master documents, or subdocuments--but at first I did not know just why they were there. They, in essence were temporary kludges included for workarounds to some OOo bugs--but there was little documentation, usually none, as to their purpose or even their existence.

The problem with employing kludges without documentation is that anybody having to maintain such templates, master documents, or subdocuments is most often not let into the "secrets." One, much better way of employing documentation kludges is to append some very simple semi-permanent documentation that stays with the documents until the kludges are no longer needed (due to developers eventually fixing the code, etc.) and afterward they (both the kludge and its documentation) can be simply removed.

A simple manner of documenting a kludge would be to append a simple comment (Insert > Comment) to that segment of the document and simply keep it there indefinitely--until it is no longer needed--after the kludge is removed, hopefully. OOo and LO documenters do not seem to do that... It was our fault as "sloppy" technical editors and writers not to adequately disclose such esoterics.

So, in everything that I do involving any such kludges, I will append simple documentation disclosure, so that any of my works can be easily and readily maintained by third parties. I recommend that LO documenters do likewise.

Gary