TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Names in Examples From:Mike Christie <mikec -at- LUNA -dot- SYNTEL -dot- COM> Date:Thu, 16 Feb 1995 09:15:13 -0800
> 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.
Syntelligence Systems, Inc.
mikec -at- syntel -dot- com