Re: Paragraph numbering - industry standard?

Subject: Re: Paragraph numbering - industry standard?
From: David Neeley <dbneeley -at- gmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 4 Aug 2005 10:45:32 -0500


Always interesting to see a provocative opinion based upon reason--in
whole or in part!

First, an observation. When you said:

> If you can't be
> bothered to put the TINY effort into numbering the doc, what are the
> chance the effort will be expended to index properly?

It becomes apparent you haven't been working in autonumbering in Word
much! Despite any other reputed strengths or weaknesses, I think there
is no comparison between autonumbering in Frame and what passes for
autonumbering in Word with a complex document.

That said, let me deal with a middle path amidst all the positions
being expressed.

Two kinds of documents have extensive numbering schemes--military docs
and statutory law. In both cases, changes are very difficult to deal
with because entire ranges have to be striken or added, making it very
difficult to be sure that something is not being missed here and
there--and making the whole thing much less accessible to a casual
inquiry by a person not very experienced.

However, in many areas of documentation, it is the depth of the
numbering scheme that makes a huge difference. Numbering individual
paragraphs that are not themselves topics significant enough to be
considered sections quickly reaches the point of diminishing returns.
Humans are not well suited to remembering five-level-deep number
sequences, I'm afraid.

Many procedural sections are not aided by having each sub-step begin
with a complex number, especially when the entire procedure properly
"chunked" should be referred to when there are questions. In my
experience, a great deal of careful thought should be done prior to
introducing more than a three-level numbering system--generally, at
the point that a decent TOC will not include numbers, that should
usually serve as a clue that the parts that aren't in the TOC
shouldn't be separately numbered, either.

On the other hand, some kinds of documents require that sort of
reference and precision. Health and safety documents, for example,
would seem to be among these--so much so that in many cases, they
should be treated like laws or military regulations with numbers that
continue from version to version of the document if possible. That
way, people dealing with older editions of the document can be easily
identified at times that are critical and mistakes dangerous.

Like so much else in life, therefore, I think that some reasonable
numbering plan should obtain consistent with the nature of the
document and its audience and not because of some prejudice one way or
another on the subject.

Finally, there often seems what to me is a misunderstanding about
document design. In my opinion, "good design" isn't about what's
"pretty" or "artistic" but about what works as well as possible for
the intended audience.

For example, the original SGML effort was stimulated by the government
because of many errors on military flightlines and in parts and repair
depots. It was considered bad enough that a single aircraft might have
four to six hundred feet of shelfspace devoted to all its repair
manuals, but when the thousands of suppliers used different document
designs, line mechanics and support people were frequently confused
and could not readily locate the information they needed. This was
costly for the government and sometimes fatal for crews. By divorcing
structure from content to a significant degree, each government
organization could apply its own DTD and get all the manuals in a form
they were accustomed to, reducing errors and saving a great deal of
money in the long run.

I am quite sure that some of the publications people at the various
suppliers had more attractive document designs than the military
used--some, if judged in the abstract, may have actually been far
superior. However, in that application consistency of design was a
positive virtue.

This is but one example that "good design" is often quite different
depending upon who is supplying the definition, but it should begin
with careful attention to what is most effective for the audience.



Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

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 for more resources and info.

RE: Paragraph numbering - industry standard?: From: Claire Conant
RE: Paragraph numbering - industry standard?: From: eric . dunn

Previous by Author: Re: Repair Parts List Organization
Next by Author: Re: Agile programming
Previous by Thread: RE: Paragraph numbering - industry standard?
Next by Thread: RE: Paragraph numbering - industry standard?

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

Sponsored Ads