Re: How do I show an example?

[Mike Pope <mikep -at- ASYMETRIX -dot- COM>]

From your descrption of the product, it doesn't sound as if you'd be working
with real novices here. (Perhaps I'm misinterpreting here.) I'd think that a
single example
could suffice, if

* you ran up to it by saying something like "similar to the
  one illustrated in Figure xx"
* you could use callouts to point out the elements of the
  example that would always appear.

I can't help but quote here a statement that appears in the manual for the
1.0 version of RoboHelp, a Windows Help
authoring utility:

     "... you'll find that the screen shots in the manual
     are from the Word 1.1 product. I like to believe
     that the average person is clever enough to recognize
     and understand the minor differences between what
     they'll see in the manual and what appears on the
     screen. [...]"

Just the right tone, I think: a) we're not responsible for providing exact
versions of what's in the product, and b) if
you can't figure it out, you're clearly not clever enough
to use our product. Brilliant.

 -- Mike Pope
mikep -at- asymetrix -dot- com

 ----------
>From: TECHWR-L
>To: Multiple recipients of list TECHWR-L
>Subject: How do I show an example?
>Date: Wednesday, May 18, 1994 2:37PM

>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-
>y+(*)
>                  |ACD, Terre Haute, IN -- The Silicon Cornfield