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.
Reena Misra wondered: <<My engineering manager wants me to include
chapter numbers for each major topic heading in an online help (chm
format). He argues that it's easy to refer to a chapter number
specially while answering customer support calls.>>
That's an interesting point, now that I think of it. If part of your
company's technical support script is to refer someone to the correct
page or section of the printed manual, online help provides no
comparable "hooks", and it can be quite awkard to have to describe a
long navigation path to get to a topic, or explain which of several
index keywords to click on, or what phrase to search on. Cool idea!
<<So, should an online help have chapter numbers?>>
It's certainly true that a chapter number can't hurt, but on the other
hand, assigning chapters to something that is inherently nonlinear can
be misleading if the chapters suggest a structure that doesn't exist.
If your help is structured in such a way that it _does_ fall naturally
into chapters (e.g., if at least part of the system is intended for
linear browsing, as in the case of a printed manual that has been
dumped online and supplemented with context-sensitive links), then it's
easy to add chapter and section numbers to your topics, and ensure that
those numbers appear in the table of contents for the help system.
However, if you've got a truly nonlinear structure, that clearly won't
work. The question then becomes the following: How can you meet the
design goal of making it easy for tech support to refer to a single
help topic amidst hundreds or thousands of other topics? I don't have
an easy answer, but I do have a few thoughts that might lead to one.
It's certainly possible and even easy to assign a unique ID number to
each help topic (you're already doing this when you assign a topic ID
to permit context sensitive links), and your support staff can then
simply refer to that number.
The problem with numbers is that they're difficult for humans to
remember, and they provide no mental "hooks" that will help someone
find that same topic again: compare the task, 6 months after your call
to tech support, of looking for "the print topic" versus "topic ID
2948765412". Plus, as my silly example shows, engineer/programmer types
tend to like long, complicated numbers, with far more digits than are
necessary. Avoid the temptation to create hugely long numbers if you
choose a numeric approach. Smaller numbers are much more user-friendly.
Words are better, though. Compare "go to help topic 123456" with "go to
Chapter 5, on printing, and look up the section named 'print what' for
details". Which is easier to understand and use? The answer suggests a
partial solution: Create a simple coding system for each type of help
topic, and use that to "assemble" a list of keywords. For example, you
might choose the keywords "menu" and "dialog" to define help topics
that fall under the groups for menu choices and dialog boxes,
respectively. You could then add additional keywords such as the name
of the menu choice or dialog box. You could then tell the user to look
up the following keywords, for one example: "menu" plus "File" plus
"Print". This would quickly find the help topic for the Print command.
This would work particularly well if you supplemented it with an
expanding and contracting "tree" structure to provide access to
individual topics. That's the kind of structure that uses little [+]
icons beside a topic to indicate that you can expand it, and little [-]
icons beside a topic to collapse it and conceal the choices. So you
might see something like the following:
[+] Dialog boxes
[-] Menus
[-] File menu
Open
Save
Print
[+] Edit menu
[+] Tools menu
[+] Tutorials
<<Besides, online help of popular tools do not have chapter numbers!>>
"Nobody else does it" is a poor justification for not doing something
innovative that will help your audience. In my opinion, there's very
little modern online help from Microsoft, Adobe, et al. that I find to
be of high quality (no offence to my fellow listmates, I hope).
Imitating poorly written and designed help systems only perpetuates the
problem.
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
---
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.
