Sometimes, a sense of humor helps with technical documentation
Sun 27 Aug 2006, 11:29 PMTweet
by Ben Langhinrichs
As we all know, reading technical documentation is not always entertaining. Lots of lists of parameters and options, and your head can start spinning. For example, I am reading through Chapter 3. Text Document Basics, which is part of the OASIS OpenDocument Essentials book (still a heck of a lot less painful than the official ODF specs), and there are lots of entries such as:
- This attribute is used to create superscripts and subscripts. It can have two values; the first value is either sub or super, or a number which is the percentage of the line height (positive for superscripts, negative for subscripts). An optional second value gives the text height as a percentage of the current font height. Examples: style:text-position="super" produces normal superscripts, and style:text-position="-30 50" produces a subscript at 30% of the font height below the baseline, with letters 50% of the current font height.
Erp! But mixed in with the more dry entries, there are a few which show a healthy sense of humor peeking through, such as
- Oy, you wouldn’t believe how many underlining styles you have available to you! none, single, double, dotted, dash, long-dash, dot-dash, dot-dot-dash, wave, bold, bold-dotted, bold-dash, bold-long-dash, bold-dot-dash, bold-dot-dot-dash, bold-wave, double-wave, and small-wave. The style:text-underline-color is specified as in fo:color and has the additional value of font-color, which makes the underline color the same as the current text color.
or one of my favorites,
- Set to true if you want the readers of your document to hate you forever.
Now, that is truth in advertising!
Copyright © 2006 Genii Software Ltd.
What has been said:
483.1. Det Prins (08/29/2006 01:38 PM)
If anyone made my text blink, I'd probably hunt them down and make them regret it in a socially unacceptable manner.
483.2. Gregg Eldred (08/31/2006 08:31 AM)
I have found some humor in Lotus Designer Help. If you know some of the developers, some of the @Functions reference real Lotus/Iris people