Do you include a sentence identifying the dialog name?

["Chris Knight" <cknight -at- attcanada -dot- ca>]

I generally use the approach Janice Gelb gave us, and would agree with her
cautioning writers against Philip's suggestion "I combine the sentences.
"Choose Database -> Password to display the Change Password dialog."
Janice is quite correct in saying that "The user is not choosing the menu
option to display a dialog box. ("Oh, look -- cool dialog box!") The user is
choosing the menu option to do a task. The dialog box just happens to be the
means through which the user can do the task."

In addition, it is totally backasswards to give the purpose for an action
AFTER describing how to do the action. Where it is useful to tell a reader
what the purpose is (and it is certainly useful to do so in many cases),
give the purpose FIRST. Why? The purpose may not be what the reader had in
mind! If that is the case, s/he doesn't have to read that step (or
procedure). Writing this way saves the readers' time, and I have direct
testimony from readers that they really appreciate this.

That being said, I am intrigued by Christine Anameier's approach, which is
even more terse.
The key feature in her approach is avoiding the "<Splat> dialog box appears"
line, while still maintaining the name of the dialog box in the next step.
True, this approach loses some of the re-assurance that the "<Splat> dialog
box appears" line allows, but if the dialog box is used in ONLY this place
in the document, Christine's approach is maximally minimal (which is good).
If the dialog box is used in other contexts, and I wanted the reader to be
that extra bit aware of its name, I'd stick with the "<Splat> dialog box
appears" line.

One more point: Gilda, why do you index the dialog box NAME? Indexes, like
user guides, should be task-oriented. I really doubt that anyone will look
up the dialog box name in the index. Index "password", "password, user", or
"password, changing", or, even better, all three--not the dialog box name.

Now, maybe we could go on to the subject of whether or not the *screen shot*
is necessary.
Up till now I have always included it (for reassurance), but perhaps in
cases where the dialog box ONLY makes its appearance within this one
procedure, the same argument might hold--why bother?
If the dialog box is referenced elsewhere, or is complicated, with lots of
UI widgets, I'd still keep the screen shot.

Interesting questions!

Chris
_____________________________________
Christopher Knight, Technical Communicator
http://members.attcanada.ca/~cknight/
E-mail: cknight -at- attcanada -dot- ca
Phone: (604) 877-0074

PS  I'm on the digest. If you respond to me on the list, please respond to
me directly as well.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ 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 
http://www.raycomm.com/techwhirl/ for more resources and info.