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.
This numbered headings thing seems to be a religious-type
debate, but for what it's worth here's why I prefer them.
1) For the reader:
a) "see the section `wibbling the wotsit' for
more details" doesn't help me find the right
place at all...
b) "see page 87" allows me to turn to page 87
pretty easily, but where on page 87 do I read?
All of it? From the top? Or is the section heading
halfway down relevant? What if there are two
headings on that page? Is page 88 also relevant?
What about page 89?
c) "see Section 6.5 for more details of wotsit
wibbling" tells me that I need to read a particular
section. I can easily find the page number in the
table of contents (because the number tells me
exactly where in the TOC to look). Plus it's fairly
easy to find chapter 6 and thumb through to 6.3.
I know that all of 6.3 is relevant to the issue
at hand - of course I could have been told that
only 6.3.2 was relevant. So I know where to start
reading, and where to stop.
2) For the writer:
a) Referring to a section or passage by heading
name is a problem. What if I later decide to
change that heading name (or worse, if someone
else does)? I would then have to alter all the
references. How would I find them all? How would
I know I had any to find?
b) Referring to a page number is ok, but I'd better
be careful with situations where the text I'm
referring to happens to come out either right at
the top or right at the bottom of the page in
question, or risk annoying my reader
c) Referring to a given section symbolically will
never need any maintainence, and of course doesn't
prevent me from saying "the definition of this
function can be found on page 87" when I'm
referring to a smaller, or atomic, item, rather
than a section or sub-section.
Having said all of that; I agree that documents with
bumpteen levels ("see Section 84.3.5.11.6") are
self-defeating. Three levels seems sensible for most
applications, operating systems for nuclear reactors
apart...
Christopher Gooch, Technical Author
LightWork Design Ltd, Sheffield, UK.
chris -dot- gooch -at- lightworkdesign -dot- com
www.lightworkdesign.com
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.
