Alternatives to numbering, take II

Subject: Alternatives to numbering, take II
From: Geoff Hart <Geoff-h -at- MTL -dot- FERIC -dot- CA>
Date: Mon, 9 Aug 1999 08:48:00 -0400

Joanne Grey continued the thread on numbering sections:
<<Unfortunately, for what my client wants, there seems to be
no real alternative. In order for the end users to refer to a
specific chapter and section regardless of the language and
page numbering, section numbering seems to be the only
realistic way to do it.>>

In that case, the trick is to minimize the impact of the
numbering scheme. Based largely on personal preference and
limited observations (thus, ymmv), I'd rework the document
structure to (wherever possible) use no more than four
hierarchical levels: Chapter number, Heading (1), subheading
(1.1), and third-level heading (1.1.1). Anything much deeper
(i.e., more than 3 digits) makes it difficult or impossible for
readers to grasp the overall structure of the document*, even
though how lower-level headings relate to which higher-level
headings becomes clearer. (The actual number will vary from
reader to reader; in my experience, three levels is pretty
simple for almost anyone to grasp, and that suggests it's a
reasonable cutoff point for a general audience.)

* That's a bit tricky to define. What I mean is that by the time
you're reading section 1.2.3.4.5, with the title
"troubleshooting", it's a bit of a chore to remember the four
previous levels of heading that got you to this point and thus
define the context for the current chunk (e.g., 1. Developing
heading structures, 1.2. For printed documents, 1.2.3. For use
in North America, 1.2.3.4. When you have to produce online
docs too, 1.2.3.4.5. Troubleshooting). The reason this is
important is that readers won't generally be reading your docs
from cover to cover, and will probably jump into a particular
paragraph via the index or by skimming through a chapter;
the deeper the hierarchy, the harder it becomes to determine
the context/path that led to that heading.

The way you work around this problem is by flattening the
hierarchy wherever possible. For example, instead of having
one main heading entitled "10. Printing", with two subheads
("10.1 locally" and "10.2 over the Internet") that each have
several levels of subheadings, create two new main headings
("10. Printing locally" and "11. Printing over the Internet"). In
fact, depending on how large the text is for these sections,
you might even turn each one into its own chapter. By doing
so, you've eliminated one whole level of heading (thereby
making the context clearer), grouped the information into
more digestible chunks, and mitigated to some extent the
potential impact (fear of complexity) of four-digit or larger
section numbers.

--Geoff Hart @8^{)} Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"The text's out of joint, oh cursed spite/that ever I was born to set it
right."--Prince Hamlet, early Danish editor

From ??? -at- ??? Sun Jan 00 00:00:00 0000=


Previous by Author: Use of "you" in documentation?
Next by Author: Pricing of documentation?
Previous by Thread: Getting a TC Job
Next by Thread: Re: Alternatives to numbering, take II


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


Sponsored Ads