Re: How do I show an example?

[John Gough <john -at- ATRIUM -dot- COM>]

We're having fun now...

First, the direct answer:

Option 1: if there is a large or indeterminate number of object classes,
          do show a representative window and label it as such.  (If
          this is the case, you're probably dealing with a programming
          tool, and programmers certainly ought to understand the
          concept of.)

Option 2: if there is a finite number of object classes, do the same
          thing. BUT, in addition, you can
          create a reference section of the documentation that shows
          each.  You are probably writing in a guide, where you just
          need the concept across.

Now for the general opinion:

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.  An object instance is always uniquely
identified by a name, so when I need to abstract that (in command
lines, for example), I use a token like _serverName_.

    Example: when I read the specs, a command or API might read
             like this:

             goober -c _objectClass_ -z"attributes" _objectInstance_

             I replaced _objectInstance_ as follows:
             if 'goober' only worked on one class of object, I
             reflected that: _boatName_
             otherwise, I used _objectName_

Look mom, no 'instance'!  In the text, I talk about 'the boat', 'the
object', or 'the name', as fits the situation.

When our stuff is implemented at the user level, I try to
get the GUI designer to focus on names of things (boat),
rather than the abstractions that give them birth.
Concreteness increases ease of use, especially for the
level of the audience that uses the GUIs.

Hope this helps.

John
----------------------------------------------------------------
John Gough    Atrium Technologies   Austin TX    john -at- atrium -dot- com


> 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