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.
Benny Joseph is <<... working on some user manuals... I use outline numbered
heading styles. And these numbers are cross-referred everywhere. But almost
all the manuals I have seen do not use numbered heading styles at all. I
find it confusing. Is it the standard way of doing it?>>
"The nice thing about standards is that there are so many to choose from."
<g> As your colleague noted, this is certainly common in legal documents,
and (I suspect but have no firsthand experience) in military stuff. You'll
have to define your audience's expectations before you can say whether
numbered headings are a good idea; most consumer software _doesn't_ use this
style in its documentation, so it's likely to be unfamiliar to a consumer
audience. Not necessarily unfamiliar to the extent that it causes problems,
but certainly unfamiliar.
<<I believe that it is easier to locate topics, if there are numbers with
their titles.>>
It's emphatically not significantly easier than saying "see: More
information on printing (page 73)"; in fact, the latter approach makes more
sense for a general audience, since it tells the reader what information to
expect when they turn to that page, whereas saying "see section 1.1.1.2"
provides no context. Moreover, it's a lot easier to turn to page 73 than it
is to skim through hundreds of pages looking for section 1.1.1.2; the
Chicago Manual of Style, an otherwise marvelous reference, drives me batty
when I have to find a specific subsection. There's an obvious and very
important exception to this rule of thumb: where the numbering scheme is so
well-defined and universal for a specific subject that everyone has long
since memorized the numbering scheme and uses it unconsciously. To them, the
numbers are meaningful, and thus, serve as an efficient tool for indicating
context. It's like using a manual transmission: a powerful tool for those
who use it, but it's only easier to use than an automatic transmission in
specific situations and for people who have practiced this skill.
<<Also, it would tell the reader immediately where the topic relates to.>>
Nope. Quick quiz: can you tell me, without looking at your own manual, what
topic 17.1.3 is, and how it relates to subtopic 17.1.3.4? Didn't think so.
Numbers used to be useful for cross-references in the good ol' days when you
couldn't automatically create cross-references to headings and page numbers;
now that you can do both, I don't see much use to numbered headings.
Moreover, there's a serious usability issue with heading hierarchies so
complex that they require numbering. One place where Miller's work on
short-term memory is likely to apply strongly is in situations where readers
have to keep multiple heading levels in their head simultaneously. For
example: "This is the reference section for the QMS laser printer for the
Postscript printing subtopic for the Printing on Paper topic in the chapter
on Producing Output in Electronic or Print Form". See the problem? That's a
large chunk of context for anyone to keep straight while they actually read
the reference information. Numbering the headings makes the problem worse
because the numbers provide no context at all (with the exception noted
above).
--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
"How are SF writers like technical writers? Well, we both write about the
things we imagine will happen in the future!"--Sue Gallagher
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.comhttp://www.miramo.com +++
---
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.
