RE: Suggestions welcome for this brief online help sample

["Joe Malin" <jmalin -at- tuvox -dot- com>]

Hi!

My first comment is that I always used "enter" rather than "type" but
Microsoft Manual of Style (MMS) prefers "type".

I use bold to indicate the names of GUI elements *except for* dialog
box, message box, property sheet, and window titles. This is a style
variation I picked up in a previous position. We decided to do this to
cut down somewhat on the use of bold; we had a very dialog-rich UI. As I
remember, we also decided that users don't always notice the titles.

I also use "appears" rather than "opens". I only use "display" as a
transitive verb. So in Number 8, I would say the "new widget appears in
the list box, preceded by its assigned color." 

MMS says "click" is preferred to "click on".

I query the customer on point 7: Does the UI we are documenting *always*
say "OK"? If so, my advice is to say "Click OK" (OK in bold). if it
isn't always OK, we should put whatever it is. This does depend on the
expected audience; if they are computer literate we can omit it, but
then we should do that consistently.


I try to make my steps a bit longer, especially for computer literate
users. For example, I would say
1. Click Define a New Widget [The string should be exactly as it appears
in the UI, regardless of grammar]
2. Type the new widget name in the text box, then click Enter. A color
dialog box appears.
3. Click your color choice from the Basic Colors, Custom Colors, or
Color Matrix. 
   To save a color to the Custom Colors, click Add to Custom Colors.
4. Click OK. The new widget now appears in the list box, preceded by its
assigned color. 
   By default, the new widget is active.
5. To deactivate the widget, click the name and clear the Active check
box.

Joe


Joe Malin
Technical Writer
(408)625-1623
jmalin -at- tuvox -dot- com 
www.tuvox.com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.	

-----Original Message-----
From: bounce-techwr-l-216553 -at- lists -dot- techwr-l -dot- com
[mailto:bounce-techwr-l-216553 -at- lists -dot- techwr-l -dot- com] On Behalf Of Karen
Sent: Thursday, November 03, 2005 9:26 AM
To: TECHWR-L
Subject: Suggestions welcome for this brief online help sample


Please forgive the widget example; however, I'm working on help screens
for unreleased software.

To add a widget


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Try WebWorks ePublisher Pro for Word today! Smooth migration of legacy
RoboHelp content into your new Help systems. EContent Magazine Decision-
maker review (October 2005) is here: http://www.webworks.com/techwr-l

Doc-To-Help 2005 converts RoboHelp files with one click. Author with Word or any HTML editor. Visit our site to see a conversion demo movie and learn more. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.