Sometimes, a sense of humor helps with technical documentation

Sun 27 Aug 2006, 11:29 PM

Tweet

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:

style:text-position

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

style:text-underline, style:text-underline-color

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,

style:text-blinking

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.