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.
Rowena Hart reports: <<Maybe I'm having a bad day, but I'm doubting the
value of using the procedural style outlined
in the Microsoft Manual of Style for Technical Publications in my help
topics.>>
Gee... anyone who doubts Microsoft's style recommendations is having what
I'd call a _good_ day. <g>
<<Every screen/page in the app has an average of 15 drop-down lists and text
boxes. The average user will be an experienced financial professional, but
they won't necessarily be an experienced ASP application user. I'm concerned
that I will p***-off my users by using the MMoSTP procedural style, i.e. "In
the Currency drop-down list, select the currency of this transaction." I
suspect that this kind of detail is unnecessary, based on the level of
financial knowledge the product's users will have. It also makes for *very
long* procedures.>>
If the fields, dropdown menus, and tabs are all clearly defined, you
probably don't have to refer to them each time, and particularly not if the
steps follow the order of the fields on the screen. I started out naming all
the fields in my documentation, but I've gradually came to feel that this
approach is too basic for an engaged and intelligent reader. Of course, some
people using your software may really need to be led by the hand, and in
that case, the Microsoft approach makes some sense. I like your approach of
defining the field-level help separately from the procedural help. This is
particularly effective if you've worked with the developers to produce
effective labels for the fields and have included appropriate affordances
(i.e., clues that show them what a field means or how to use the field).
<<Which is better in this situation-- detailed or high-level?>>
This always depends on the audience. Given that they're mixed (they
understand the subject but perhaps not the interface):
<<What are some alternative procedural styles that I could use in this
situation?>>
An interesting alternative would be a hybrid of visual plus textual: Provide
a screenshot of the dialog box or form, with the fields numbered in the same
order you'd recommend they follow to complete the procedure. Beside this,
with numbers that correspond to the screenshot, display the step and its
explanation. This provides context ("where am I in the dialog box and in the
procedure as a whole?"), eliminates the need to retype the field name each
time (since it's present in the screenshot), and ties the instructions
directly to the image the reader is seeing in the application screen.
This approach can be awkward for large and complex dialog boxes; in this
case, you'll have to modify the approach. Two examples might be to crop the
dialog box to show just the step that the image describes or to display the
entire dialog box, but only show three or four numbered steps at a time. In
the latter approach, you'd show steps 1-4 on the first shot, then 5-8 on the
second, and so on. The number of steps per screenshot would depend on how
long the steps are: the longer the steps, the fewer you'd use with a
screenshot, because both the steps and the image they refer to should appear
on the same screen wherever possible.
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit http://ieeepcs.org/2001
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
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.
