SUMMARY: Pros/Cons of Section Numbering (long)

[Mary Anthony <mary -at- PERSISTENCE -dot- COM>]

Hello,

As requested, I am publishing a summary of the PROS and CONS of section
numbering.  I have paraphrased a list of the "distilled" pros/cons in the
discussion below.  The distilled version consist of the pros/cons that
seemed to appear most often in the thread (in one way or another).  BTW,
there is no significance to position of a particular item on each list.

Additionally, I have quoted tips and words of wisdom received during the
course of the thread.  These are items that caught my eye YMMV.

My thanks again for everyone who contributed.  The results appear to be a
draw.

Regards,

Mary

---------Begin Summary


Section numbering is BAD because it:

1) Creates a lot of "noise" in a document's layout.
2) Intimidatea less-technical or novice users.
3) Makes the "Table of Contents" harder to scan.
4) Results in shortened headings (as a result less useful) to allow room for
the numbering.
5) Distracts the reader's attention from the heading itself -- the eye jumps
to the number instead.


Section numbering is GOOD because it:

1) Provides a greater level of information in cross references.
2) Makes the logical structure of the document visible.
3) Acts as a "you are here" navigational device in long sections.
4) Makes the distinction between head levels easily visible to users.
5) Assists in documentation maintenance by allowing the writer to make
changes to the appropriate sections and leave the rest of the document alone.



from Susan Gallagher:

>In general, the more technical the audience, and the more technical
>and cross-referenced the manual, the more "user-friendly" section
>numbers become.

>Non-technical users can be intimidated by section numbers because
>they do make a lot of noise. And if a manual is not heavily cross-
>referenced, the reasons for section numbering disappear.

from Ian White

>In general, it's much harder to write documentation whose structure is
>completely self-explanatory without some help from a multi-level
>numbering scheme. If the page layout already includes a wide left
>margin, progressive indenting alone is definitely not the answer.

>When editing reports written by engineers and scientists I find that
>formal section numbering imposes a discipline on the writer to organize
>the material in a logical way, and it thus makes my job easier.

>Maybe the answer is that any technical writing should be sufficiently
>well-organized that it *could* accept a rigorous, formal numbering
>system; but that readers don't always need it.

from Robert Plamondon:

>Section numbering illuminates the logical structure of the document (if
>any).  This is a Good Thing.  With simple documents covering simple
>subjects, section numbering is unnecessary.  You don't need numbered
>sections in a chapter called, "How to Make Toast in Your Toaster."
>On the other hand, you can't turn "Periodic Maintenence of the
>Falcon Missile" into a user-friendly toaster manual by omitting the
>section headings.

from D.T. Robertson:

>By training/education (PhD Chemistry) and experience I'm a technical person.
>Most of the documents I come across have section numbers.  I use them
>extensively myself.  Us techies tend to like numbers!  But, I agree
>wholeheartedly with the majority opinion that their use must be determined
>by the preferences of the audience.

from Mary Anthony:

>My personal opinion regarding section numbering, is
>that section numbering is unnecessary for commercial documentation, that
> indentation or font changes supply adequate visual cues for
> readers.

from Karen P. Wiley:

>It can get carried away, of course, where every paragraph
>has a new number, and sections go 8 digits or so (which can be more
>confusing than no numbers at all). But if you need to refer to
>other sections it is much more useful to have that section number rather than
>saying 3 paragraphs previous or the like.

> I think it is all what works for
>your audience (customer); what he expects and thinks looks good.  It also
>depends on the complexity of your document and your need to direct the reader
>to other parts of that document.

from Chris Hamilton:

>At that time, one of the reasons section numbers were good was that we
>were using courier 10 and only had bold and underline.  That limits your
>visual tools for differentiating levels of detail.


from Beverly Parks:

> I think the material is the deciding factor, more so than the audience
> in this case.
>If you use lots of subheadings and the text under those subheadings is
>short (less than a full page), then it is simple just to refer to the
>heading and page number; i.e., see Installing the Widget on page 2.

>OTOH, if you have multiple pages of text underneath a single heading,
>then paragraph numbering may be necessary. Having only numbered headings
>won't be any more help than unnumbered headings in this case.

from Win Day:

>If you update your manual piece by piece, rather than reissuing the whole
>thing, numbered sections stored in a binder are easier to update.
>Supposedly.  End users who actually insert the updates into their manuals
>are few and far between!

from Caryn Rizell:

>  I am a strong opponent of using section numbering.  These days, with
>     sophisticated tools like FrameMaker, you can easily do
>     cross-references to a particular page or paragraph, so you don't need
>     to use the section numbers for reference.

from Joanna Sheldon:

>As for section numbers, in some cases (in a recipe for example, or
>instructions on how to use a simple piece of household equipment, or a
>user's guide in which the subsections are few and can be clearly marked with
>a different point size) they merely distract attention from the content.

from Tom Neuburger:

>On the "con" side, there's the fact that the eye can't find the
>heading text because it jumps to the number. I would delete
>the number and write headings that can be read at a glance --
>not necessarily short ones, but put the key words early in the line.

from David Locke:

>A solution I have used is to set the numbers at 8 points Sans Serif and put
>them in the margin.

>To get rid of section numbering, do a usability study and ask readers if
>they refer to sections that way. Lawyers do. Nobody I ever met remembers a
>section by number or heading, they remember the topic.

from Maria Hunt:

>I managed to convince my co-worker to get rid of section numbering by
>explaining that it did not support Microsoft's style and it would look
>terrible when the text appeared in online help.

Other Lists of Pros/Cons on the Web:

http://www.pip.dknet.dk/~pip323/tip-9605.htm
(an informative link supplied by Peter Ring)

     Searchable archives located at http://www.documentation.com/
           ALL questions or problems concerning the list
      should go to the listowner, Eric Ray at ejray -at- ionet -dot- net -dot-