Names in Examples

[Mike Christie <mikec -at- LUNA -dot- SYNTEL -dot- COM>]

> As long as it helps to explain the feature, it is
> "meaningful to the user."

> However, I would, at all costs avoid the names of
> Star Trek characters (even Next Generation). In addition
> to creative infringement, it'll just make your company
> look like it's peopled by a bunch of technoweenie wireheads.

Which brings up another point in the use of examples/screen shots. Why *not*
use a little humor where appropriate? I really dislike humor in the text of
a manual, but I think that it has a place in examples or sample screens.
(Unless your target audience has a reputation for being absolutely humorless,
in which case you'd best stick with simple, generic examples.) In the
multi-volume manuals for the enterprise system I document, I think a little
humor adds to what otherwise can be uniformly drab set of manuals describing
the syntax of keywords, how to write external interfaces, and how to configure
CPI-C, DB2/2, and CM/2 to work with your system.

I used literary examples in the sections I added. For example, in a list
of names retrieved by a search, I included William Faulkner, Ralph Waldo
Emerson, Mark Twain, etc. In an example describing two people accessing the
same set of data simultaneously I used "Alice" and "Whiterabbit." The point is
still made and all the information is there, but the frustrated
system administrator who is trying to set up a Windows front-end
connecting to an engine on an OS/2 server with a MVS host database at
least gets a bit of a chuckle.

Mike Christie
Technical Writer
Syntelligence Systems, Inc.
mikec -at- syntel -dot- com