RE: Numbered headings?

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

Hi Scott

> -----Original Message-----
> From: quills -at- airmail -dot- net [mailto:quills -at- airmail -dot- net]
> Sent: Tuesday, September 18, 2001 9:42 AM
> To: TECHWR-L
> Subject: RE: Numbered headings?
> 
> 
> >Actually, it may tell you a lot. As it is 2.3 and not 2, you 
> >know it's a subsection. 
> >If each section has a #.3 subsection describing using the interface 
> >then you can actually use this information when looking through 
> >the TOC, Index, or paging through the manual.
> >
> >Eric L. Dunn
> 
> 
> And it is cluttered.

Give the human eye some credit for being able to ignore clutter... like
television commercials, ABC/NBC/CBS news coverage and scrolling footer
text, all sports programs displaying scores and stats, newspaper ads,
banner ads on websites, websites themselves, etc.

If the clutter (... ah, numbering) is consistently put in the same spot,
traditionally to the left of the title, it is very easy to ignore...
until you need it, like from a cross-reference.

> Structure to a document can be shown using numbering, it can also be 
> shown visually with layout.

I've done this in the past. I'm doing it now, as dictated by our style
guide. However, I can't say that the layout really conveys the true
meaning of a heading's relationship to other headings when it is 14 pt,
cursive, and indented an inch, as opposed to 14 pt, bold, and indented
only 1/2 an inch. When these two headings appear on separate pages far
apart, the distinction is easily lost.

And when I single-source that puppy into HTML, I convert all headings
1-4 into H1 anyway, because they look the best as individual HTML
documents that way. It'd be cool if the numbered hierarchy came over,
too.

> Referring to a heading is complicated because if it is a physical 
> (printed) document, you need the page number more that the heading 
> numbering. Once on the page the text description (heading text) is 
> more recognizable that numbers.

Page numbers are certainly nice. However, a reader could _almost_ as
easily find "Section 3.7.4: Cleaning Up" as they could "Section
'Cleaning Up' on page 3-12," particularly if heading information is
included as part of the header/footer.

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.

1) You only need one cross-reference with the section number and title.
(In Word, you'd have to have two cross-references to get title and page
number. Although FM supports putting title and page number in the same
cross-reference, you'll still need separate cross-references for title
only, page number only, etc. If you're not putting page numbers in, you
can get by with one cross-reference format.)

2) You don't need (as much) conditional text and other easy-to-screw-up
mechanisms to separate print-only/PDF-only outputs from online-only
outputs. All of your cross-references valid for online and print would
simply have section and title. 

3) 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.

4) Numbered heirarchies in the headings are easier for the writers to
understand at a glance. With heirarchy embedded in formatting, I have to
generate the table of contents to truly understand the structure of what
I've written.

5) Numbered heirarchies in the headings are easier for the readers to
understand at a glance. This is particularly true when single-sourced
into an online medium.

 
> Numbering headings down past two level is often counter-productive, 
> as is numbering when the numbers reach obtuse lengths such as having 
> more than two digits throughout the number (2.13.2.23). Then you have 
> users encountering problems when they mis-read and instead go to 
> 2.13.23.3.

There certainly is truth to this.

However, nobody says that your style guide has to assign numbers to
headings below the second or third level. The fourth level and below are
probably acceptable to distinguish using just formatting; you may never
extract them out to the TOC. 

In our case, we assign numbers to only the top level and only take the
top four levels to the TOC (chapter, heading 1-3). It wouldn't bother me
to assign numbers to the top three levels (chapter, heading 1-2) and
still take four levels to the TOC.

 
> Any way you look at it, the layout must support the information. 
> Numbers by themselves do not impart a lot of information. 

True. But numbers do impart some information which is more information
than 12 pt, bold, and indented 1.5" conveys when looked at in context.
They definitely impart some information when included in a hyperlink and
they are easier to gloss-over/find acceptable/ignore in an online medium
than a page number.

> You have to tailor your schema to meet your objective.

True. Find out how many levels could benefit from numbers; not all
levels do, even though the headings might be part of the heirarchy
scheme and useful from that perspective.

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- 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.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.