Summary- Part 2: Numbered headings

[Benny Joseph <benny -at- mascon -dot- co -dot- in>]

Hi All,
This is the second part of the summary of discussions on the subject. 
Thanks, once again.
Benny


Horace Smith wrote:
Yes, yes, yes. Pay no attention to the software wrliters on this list. Your
readers will love you for it.

Jim Morgan wrote:
(Numbered headings) they may still be required in some of your documents.
For example, the quality certification my company intends to seek requires
that policy specifications use section numbering.

Margaret Beilby wrote:
1. Our standard is to used numbered headings/sections for technical manuals
(programming, guides, system administration guides, etc.) and unnumbered
headings for end-user guides.
2. Many technical people are used to this format and really prefer it. For
the most part they prefer numbering because it's easier to refer to the
sections in the document.
3. The other reason is that many technical people are also non-native
speakers of English. The numbered headings give them an additional "road
sign" and makes it easier for them to use the documents.

William Hand wrote:
1. To number or not number, depends on what the customer wants.
2. I prefer numbered paragraphs, I find that they are much easer to locate
paragraphs in documents where the layout and formatting have been given some
thought.

Christopher Gooch wrote:
Why I prefer them (Numbered headings: 

1) For the reader:

a. "see page 87" allows me to turn to page 87 pretty easily, but where on
page 87 do I read? 
b. "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). 
2) For the writer:

a. 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. Having said all of that; I agree that documents with umpteen levels ("see
Section 84.3.5.11.6") are self-defeating. Three levels seems sensible for
most applications, operating systems for nuclear reactors apart...

Summary:
1. If cross-reference is indicated with page number alone, it doesn't tell
where in the page to look for.
2. Finding a cross-reference with a numbered heading is easy, as one can
find the page number easily in the TOC.
3. For the writer, if there is a change in the heading text or the page
number, it has to be altered later.
4. Three levels of numbered headings are OK.

Ian Saunders wrote:
1. If your system of providing feedback demands section numbers to quote
then you *must* include them. 
2. If, however, a reviewer *must* return a list of required changes to the
writer, I concede that quoting numbers is probably neater than saying "...in
'User Interfaces' on page 29".
3. I get the feeling that section numbers are actually more useful to the
*writer* than to the user.


John Posada
1. In a really complex document (200-300 pages) where a section may be many
multiple pages, by numbering sections, you give an indication of the where
you are in the section and where you are in the document.
2. In addition, in that complex document, numbering tends to group numbered
sections so I can tell without reading each one that.

Michael Murphy wrote:
1. I like to minimize the importance of all navigational devices on a page.
That includes the heading numbers. Notice that they're all the same point
size, even though the text of the headings are different point sizes
depending on heading level.
2. I am NOT using the outline numbers when I reference a heading in the body
text...maybe I should.

Kent Christensen wrote:

(In Military Unsatisfactory Report) Paragraph numbering is pretty much
required in order that those providing feedback can easily refer to the area
of the manual where the problem occurs. The numbering is surely also used in
other forms of communication, including training.

Pallavi wrote:
1. In case of a technical document it is easier to refer if it is numbered.
2. It gives a professional look if you have a lot of sub headings, specially
for APi manuals and User manual. If you do not have a lot of sub headings,
you can ignore using numbered sub headings. 

Shauna Iannone wrote:
A system of nested, numbered headings means we can reference the relevant 
section of text in the traceability matrix by number, and updates needed to
any doc that references a changed section are easier to identify. Now, these
docs are not "end user" docs, so YMMV.  However, I believe it is
unnecessarily harsh to arbitrarily discount the benefits of numbered
headings when the contexts of usage may vary.

Patrick Rands wrote:

I think it is useful to use numbered headings when discussing different
platforms in different chapters (but with similar content). That way you
don't have headings with the same titles.

Glenn Maxey wrote:

1. As tech writing moves more and more into the realm of single sourcing
into PDF files and online help (with cost savings in production and
shipment), then having the numbering hierarchy visible in the headings pays
some small dividends over not doing it.
2. If you refer to sections with their numbers, you don't have to make page
number references that aren't relevant when single-sourced to online
formats.
3. Numbered hierarchies in the headings are easier for the writers to
understand at a glance. With hierarchy embedded in formatting, I have to
generate the table of contents to truly understand the structure of what
I've written.

Winfried Reng wrote:
1. I as a user find it rather annoying when headings don't have numbers.
Several reasons:
- Usually the headings don't differ that much in size or style that I could
tell at once which heading level that is and where it belongs to when I
don't have numbers.
- When I jump from one topic to another and want to go back I have more
problems to find the previous heading when I don't have numbers.
- When I scan the table of contents and want to go to a specific heading
it's easier not only to have page numbers but also numbered headings.
- Only when I have documents with very few headings I don't use numbered
headings.
- What I don't like: documents with 5 or even 8 heading levels. Those look
horrible and are difficult to navigate with and without numbered headings.

3. The manuals are structured according to the menu item and their sub
option levels. All the menu options are numbered in the manual.
4. At the back of the manual is a flow chart of these menu option levels
(programming map)

Jennifer O Neill wrote:
There shouldn't be more than 4 heading levels and only the first 3 should be
numbered. In my opinion that's a good compromise.

Hannah Bisell wrote:
1. I can see wanting to refer to chapter and subsection rather than page
number because as the writer revises, the page numbers are more likely to
change more frequently (and need updating) than the chapter/subsection.
2. Using numbering combined with a descriptive title the best solution so
far and my audience (mostly gov/mil workers) have responded favorably.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.com  http://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.