Re: How do I show an example?

Subject: Re: How do I show an example?
From: Jim Grey <jwg -at- ACD4 -dot- ACD -dot- COM>
Date: Thu, 19 May 1994 16:27:13 -0500

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


Previous by Author: Re: Tehcnical Writers and Software Project Management
Next by Author: Re: Computers aren't hammers (more on passives)
Previous by Thread: Re: How do I show an example?
Next by Thread: [no subject]


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


Sponsored Ads