How do I show an example?

Subject: How do I show an example?
From: Jim Grey <jwg -at- ACD4 -dot- ACD -dot- COM>
Date: Wed, 18 May 1994 14:37:27 -0500

Gentle people,

Bear with me for a short explanation of part of my company's product
technology. Then, please help me with a problem.

Our products use a notion of "Entity-Relationship modeling" to describe
the systems they manage. The products look at systems as a set of related
things ("entities"). Entities have type: "car" is a type, but "Jim's
maroon Chevy Beretta" is an instance of that type. This leads to the
notion of Attributes, which are the characteristics that make up an Entity
Type. To specify an Entity Instance, you have to give values for the

I'm documenting a tool which lets users graphically create Entity Instances
in "views" (graphic representations of groups of Entity Instances). During
creation, the user must provide values for each Entity Instance's Attributes.
So, a window appears which lets the user enter values -- but this window
is different for Entity Instances of different types, since the Attributes
differ from type to type. The window title isn't even predictable, since it
is the Entity Instance's name. (It would be easier if this thing were
*always* called "Entity Attributes" or some such.)

I want to show the window. I want to write, "When you execute this command,
the <blah> window in Figure 10 appears." But any example window I show in
Figure 10 will probably bear only abstract resemblance to the actual window
which the user sees. The common characteristics: Motif frame, with
some number of prompt objects (the Attribute names) and corresponding entry
objects (into which the user enters values). What I've tried:

o Showing exactly one example, explicitly labeling it as such. I fear that
some users will panic when the window that appears doesn't match the docs,

o Showing more than one example of this window, so the user can see what
is typical of this window, but will understand that contents vary.
Unfortunately, these windows tend to be large, and even at 50% take up
more real estate than due.

o Not showing any example window(s), but describing it briefly in text.
The description reads something like that in the paragraph before these
bullet items: it doesn't necessarily bring to mind what the things look

What do *you* think I ought to do?

jim grey
jim grey |"There ain't nothin' better in the world, you know
jwg -at- acd4 -dot- acd -dot- com |Than lyin' in the sun, listenin' to the radio" - D. Boone
jimgrey -at- delphi -dot- com|GO/M d p+ c++(-) l u+ e- m*@ s+/ n+ h f++ g- w+@ t+ r- y+(*)
|ACD, Terre Haute, IN -- The Silicon Cornfield

Previous by Author: Re: Commas in a series
Next by Author: Re: commas in a series
Previous by Thread: Re: Tehcnical Writers and Software Project Management
Next by Thread: Re: How do I show an example?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads