Re: How do I show an example?

[Jim Grey <jwg -at- ACD4 -dot- ACD -dot- COM>]

Gentle people,

Thanks to everyone who replied to my plea for help.  I got some good tips,
some of which you saw posted to the list, a few of which were sent to me
privately.  I'll respond to everyone here.

Many people echoed Glen Accardo (glen -at- softint -dot- com):

   Our product is somewhat similar.  We pretty much show one example and
   use the text to explain that they may not see anything even remotely
   similar to what the example shows.

Also, some of you pointed out that callouts or even a separate section
explaining the windows might help.  I *can* assume that the reader understands
how to read and use these windows.  Perhaps callouts for "Attribute names"
and "Here's where you enter the values" would help guide, especially after
hitting 'em across the head that THIS WINDOW IS ONLY A REPRESENTATION of
what you will see!

Anne Halsey (ach -at- tomichi -dot- stortek -dot- com) and a couple others suggested I
create a matrix to "list every possible entity attribute for every possible
entity type", or "direct the user to an appendix or supplemental reference
which shows the screen for each entity type".  Unfortunately, customers can
create their own Entity Types on the fly, thereby making the set of ETs
unknown.  A set of ETs is supplied, but that's a developer-level issue,
and this is a user-level guide.

A few shared Chuck Banks's (chuck -at- asl -dot- dl -dot- nec -dot- com) near-paydirt idea:

   How about drawing a general layout of your screens, using dashed line
   or dotted line blocks to indicated the locations of the components of
   similar windows?  Label each block in your layout or model screen.
   Then, relate any example screens to your model.  Use consistent language
   throughout.

   That's not as good as showing every screen, but our customers generally
   approve (i.e., most haven't complained) of this method.

I like this.  I think I'll combine it with what Fred Jacobson (fred -at- boole -dot- com)
and a few others said:

   I would try to devise an "abstract" example window that conained all
   the Motif and constant stuff and had a title like Example Entity
   Attribute Window and prompts like Example Attribute Prompt or Typical
   Attribute Prompt.  Or maybe Attribute1, Attribute2,

This way, the window I show is somewhat absurd, alerting the reader that
this *isn't* exactly what's gonna appear.  But with a title like "Example
EI Attributes Window" and prompts like "Attribute 1", they'll be able to
look at them like (as Maria Townsley (maria -at- msd -dot- measurex -dot- com) said) variables
in a mathematics equation.

Problem solved.  Thanks to:

Mike Pope (mikep -at- asymetrix -dot- com)       Ann Balaban (annb -at- dadd -dot- ti -dot- com)
Anne Halsey (ach -at- tomichi -dot- stortek -dot- com) Caryn Rizell (caryn -at- hpptc95 -dot- rose -dot- hp -dot- com)
Fred Jacobson (fred -at- boole -dot- com)        Chuck Banks (chuck -at- asl -dot- dl -dot- nec -dot- com)
John Gough (john -at- ATRIUM -dot- COM)          Bonni Graham (BonniG -at- aol -dot- com)
Glen Accardo (glen -at- softint -dot- com):      Maria Townsley (maria -at- msd -dot- measurex -dot- com)


Before I go away, John Gough (john -at- atrium -dot- com) had this interesting
commentary:

   Our software is based on this kind of model, too.  I can appreciate
   the usefulness of the programming constructs, but the obtuseness of
   the language is infuriating.

   In the process of writing books I've found that 'instance' is an
   unnecessary term, so I've been weeding it out. It's a very difficult
   notion to explain, partially because it's unnecessary and partly
   because the terminology doesn't have an easy metaphor in everyday
   experience.  (I try to avoid citing Plato's "The Cave" :-)

   In my writing, an 'object' is a member of an 'object class' (or type,
   depending on the product--yep, we have some consistency issues to work
   out). I haven't found a single case where I need to utter the word
   'instance' to be understood.

We use these terms:  entity, Entity Type (ET), Entity Instance (EI).
A small-e entity may or may not exist outside our NRM entity-relationship
modeling platform.  A big-E Entity Type is an abstract kind of thing as
modeled in NRM.  A big-E Entity Instance is a specific thing modeled in NRM.
In other words, as soon as you see Entity Instance, you know NRM knows about
it.  When you see entity, it's not clear, and because of context probably
doesn't matter, whether NRM knows about it.  We could have chosen Entity
instead of Entity Instance four years ago when all this started, but you
can't show capital letters in speech.  This language is very ingrained inside
the company and with our existing customers now.  So despite "instance" being
more or less unnecessary, I claim it would do us more damage than good to do
away with it now.

Peace and thanks to all,
jim grey
--
jim grey          |"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