Do you include a sentence identifying the dialog name?

Subject: Do you include a sentence identifying the dialog name?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 7 Feb 2002 11:23:41 -0500

Gilda Spitz wonders: <<Let's say we have a dialog named "Change Password".
In our procedures, we insert a numbered step consisting of two sentences:
"Choose Database -> Password. The Change Password dialog appears.", followed
by a picture of the dialog. In the second sentence, there's an index marker
for the dialog name... We're thinking of ways to improve our text, both
to ensure the English is as good as possible, and to minimize translation

I typically mention the dialog box name only when I want to reinforce a
change of context for the reader, or when I introduce a graphic. I try to
avoid "X appears" phrasings because they beg the question "when does it
appear?" and more importantly, don't really add much: readers should know
where they are because after completing the previous step, the dialog box
appears--or it doesn't, and claiming that it appears will just worry the
less secure reader.

Where I need to name the dialog box, I do it as follows:
[Context: reader is already in one dialog box, midway through a long
procedure, and will now open a second dialog box:]
22. Click the "Options" button.
23. In the Options dialog box [screenshot follows], do...

This accomplishes two goals. First, it informs readers that they must now
work in a new dialog box, and not in the original dialog that provided
access to (in this case) the Options dialog. Second, it introduces the
screenshot. I don't consider either of these reasons crucial justifications
for mentioning the dialog, and most readers will do fine without these
prompts, but in my opinion, they smooth the transition into the new context.
At the cost of only five words, I don't consider this an unjustified
imposition on their patience.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at

"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."-Kim Roper

Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for?

Have you looked at the new content on TECHWR-L lately?
See and check it out.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Search utility for HTML documentation?
Next by Author: Tables in Dreamweaver?
Previous by Thread: RE: Do you include a sentence identifying the dialog name?
Next by Thread: Re: Do you include a sentence identifying the dialog name?

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

Sponsored Ads