To number or not to number

[Marta Cepek <marta -at- M3ISYSTEMS -dot- QC -dot- CA>]

John Sturman wrote:

>>>I would like some feedback about what you all think about the use of
numbering sections in computer-related technical documentation.<<<

Personally, I prefer the numbering for the same reasons you give.

Last year the company I work for wanted to do away with heading numbering
for the other reasons you give.  Out of 8 tech writers, only 2 wanted to
keep the numbers, feeling they are an excellent heirarchical/organizational
tool for the structuring of the document.  The other 6 felt that since the
MS Word manual in particular, and a pile of other [commercial] manuals do
not use the numbering, we needn't either.  I thought that we since don't
write commercial software, why should we abide by those conventions?  To
placate us diehards, we came to a compromise.  We number levels 1 & 2, after
which the point size of the heading gets gradually smaller.  Since our user
manuals rarely go to level 4 or lower, this was an acceptable compromise to
me and the other numbering proponent.

Here are some of the arguments I felt warranted keeping the numbering:

Numbered headings make cross references clearer, such as "See section 4.3,
Updating the Watsis Screen" or simply "See section 4.3", rather than the
wordy, unwieldy "See the section on Updating the Watsis Screen later in this
chapter" (and raising the question on whether you use capitals, italics,
bold, or other emphasis on the actual section title in the xref).

Numbered headings make it really easy to find a section in a large chapter.
If you're looking for section 4.3, and you turn to a page with 4.7 on it,
you know what you're looking for is earlier in the chapter.  But if you turn
to a page with "Using the Foobar Screen" on it, you have no clue whether
it's before or after "Updating the Watsis Screen".  Pagerefs instead of
xrefs to section numbers are another possibility.

Numbering headings clearly indicates heirarchy of information.  If your
documents go beyond 3 heading levels, simply reducing the point size of your
heading font will not make it easy to distinguish between levels.  Using
indentation can get pretty ugly (far too much white space) if taken past
level 3.

However, I assumed you were talking about user documentation.
Specifications, on the other hand, we number as far down as they go (often
to level 6 and below) PLUS multi-level paragraph numbering.  This is because
in the spec review/revision process any changes can be indicated more
concisely by number rather than title, plus it provides a numbered checklist
for deliverables or compliance from the programmers.

I also thought I'd mention that I find numbering helps me to outline and
analyse the information, i.e., it forces me to break the information into
discrete parts and order it according to a logical sequence.  I'm not sure
I'd be able to *mentally* sort the information if I only had the heading title.

Anyways, those were my 2 cents.


Cheers!
Marta Cepek
marta -at- m3isystems -dot- qc -dot- ca

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Post Message:	TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Get Commands:	LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "help" in body.
Unsubscribe:	LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "signoff TECHWR-L"
Listowner:	ejray -at- ionet -dot- net