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.
RE: Do you include a sentence identifying the dialog name?Shauna Iannone
wrote:
<< 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.
Chris
_____________________________________
Christopher Knight, Technical Communicator http://members.attcanada.ca/~cknight/
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? http://www.iuniverse.com/media/techwr
---
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.
