Indexing dialog box names

Subject: Indexing dialog box names
From: "Chris Knight" <cknight -at- attcanada -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 8 Feb 2002 14:03:13 -0800

RE: Do you include a sentence identifying the dialog name?Shauna Iannone
<< Actually, in several environments, users *do* identify dialog boxes by
name (especially in cases where there are multiple related functions that
could all relate to the same single keyword), and will *first* try to look
up reference (not necc. procedural) information by the name of the dialog
box.... >>

Could you be more specific about what sort of environment this would be?
In 18 years in Technical Communication, working in a wide variety of
industries and public sector environments, I have been lucky enough on
occasion to have the opportunity to observe my target readers at work. I
paid close attention particularly to how readers looked up reference
material; many used the index, which is why (whenever I can convince my
client to budget the effort needed) I make a point of indexing user tasks.
The only environments I found where readers would reference things like
dialog box NAMES were where I was producing API documents for application
programmers. In such cases, yes, I indexed EVERY name.
What Gilda gave us did not seem like such a situation--sounded like an
end-user guide. I was questioning her practice in such a case. For all I
know, the advice was unneccessary (Gilda maybe just mentioned the DB name as
an *example* of what she indexed), but I have noticed that many
writers--even ones who can write clear concise task-oriented
procedures--don't do such a good job indexing. Many of us have not been
specifically trained in it, and tend to grasp at rather obvious things such
as "Change Password dialog box" or "File menu". Often this is what we do
first-- the "quick and dirty" index--and never get a chance to do a proper
(task-oriented) index. On the occasions where I have been able to do a
proper index, and where I have been able to do document testing, readers
often point out the index as being particulary helpful.
So, I think the counsel I gave was widely needed and *generally* applicable,
but I didn't intend it to be a one-size-fits-all approach--thank you for not
letting it stand unquestioned.

Christopher Knight, Technical Communicator
E-mail: cknight -at- attcanada -dot- ca
Phone: (604) 877-0074

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: Do you include a sentence identifying the dialog name?
Next by Author: Resume Management for Principals and Project Managers
Previous by Thread: Resume Management for Principals and Project Managers
Next by Thread: Icon Colors: Summary

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

Sponsored Ads