Re: How do I show an example?

Subject: Re: How do I show an example?
From: Caryn Rizell <caryn -at- HPPTC95 -dot- ROSE -dot- HP -dot- COM>
Date: Wed, 18 May 1994 13:22:53 PDT

Here is my two cents:

Just show one example. But before you do that, maybe include
a section on what is in these windows, what the user should
expect, what are the required fields. Then explain that
each window differs slightly based on what you mentioned.

You can always refer them back to your section talking
about the window to avoid any panic.

Caryn Rizell

> 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
> Attributes.

> 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,
> though.

> 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
> like.

> What do *you* think I ought to do?

> Thanks,
> 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-
> |ACD, Terre Haute, IN -- The Silicon Cornfield

Previous by Author: reflectionsx unix emulator
Next by Author: Re: How to Estimate Project Time?
Previous by Thread: Re: How do I show an example?
Next by Thread: Re: How do I show an example?

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

Sponsored Ads