Re: Do you include a sentence identifying the

[Janice Gelb <janiceg -at- marvin -dot- eng -dot- sun -dot- com>]

"Philip Boyer" <pboyer -at- dimasys -dot- com> 
>
> Gilda wrote: "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."
>

I find it fascinating that we've all been able to 
deconstruct a mere two sentences in so many different 
ways!
 
I agree with the people who mentioned that the 
standard is usually dialog BOX, and that the 
repetition of the dialog box name helps to  
reassure the reader. To add a point that I don't 
think I've seen made, we recommend that the only 
text on a numbered step line should be the actual 
action, so that readers can clearly see action  
they need to perform. So, in our style, this would 
be on two separate lines:

   1. Choose Database -> Password.

      The Change Password dialog box appears.
      [screen shot]

>
> I vote for identifying the dialog. It gives the 
> reader the extra assurance that he opened the 
> correct dialog and is on the right path. For my
> procedures, I combine the sentences. "Choose 
> Database -> Password to display the Change 
> Password dialog."
>

I spend a lot of time trying to train writers *out* of 
this construction. 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.


*******************************************************************
Janice Gelb                  | The only connection Sun has with       
janice -dot- gelb -at- eng -dot- sun -dot- com      | this message is the return address. 
http://www.geocities.com/Area51/8018/index.html

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.