TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: How do I show an example? From:Caryn Rizell <caryn -at- HPPTC95 -dot- ROSE -dot- HP -dot- COM> Date:Wed, 18 May 1994 13:22:53 PDT
Here is my two cents:
Just show one example. But before you do that, maybe include
a section on what is in these windows, what the user should
expect, what are the required fields. Then explain that
each window differs slightly based on what you mentioned.
You can always refer them back to your section talking
about the window to avoid any panic.
Caryn Rizell
> 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
