Re: How do I show an example?

Subject: Re: How do I show an example?
From: Mike Pope <mikep -at- ASYMETRIX -dot- COM>
Date: Wed, 18 May 1994 14:30:00 PDT

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


Previous by Author: Re: commas in a series
Next by Author: Re: Learning/researching phase of writing
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