Re: To number or not to number

[Jim Grey <jimgrey -at- IQUEST -dot- NET>]

John Sturman (jss -at- atiny -dot- ny -dot- apertus -dot- com) fears that numbering's days are
numbered:
>For as long as I have been in my present position (3 years) my department
>has been using section numbering in our documentation sets (chapter 2,
>section 2.1, section 2.1.1, etc.)
<snip>
>[Our new head] writer asserts that numbering section numbering makes a
>product look more complicated.  We are working towards making our product
>appear more user friendly.
<snip>
>My arguments for the use of numbering are that 1)it allows for easier
>random access to information in a document because it shows the hierarchy
>of sections in relation to each other so the reader can find their
>location in reference to their desired destination.  I also think that
>having section numbers makes cross-referencing much easier to implement
>and read.  We do a lot of cross-referencing to other parts of our
>documentation, so this aspect is pretty important.

*Excess* numbering makes your *manuals* look more complicated.  When
sections are numbered to beyond two places (3.2, for example), readers begin
to experience MEGO (My Eyes Glaze Over).  They can't tell 3.2.1.6.4 from
3.2.1.5.8.  The numbering becomes more distracting and confusing than
useful.  Even the U.S. Army agrees, advising writers not to use numbers
beyond two places in Army manuals.  (See Brockmann, John R., _Writing Better
Computer User Documentation: From Paper to Hypertext, Version 2.0_, John
Wiley and Sons, 1990.  ISBN 0-471-62259-1.)

Layout can provide a more immediate visual cue to document hierarchy.
Decrease the size of your heading font and decrease leading as you go deeper
into the hierarchy.  For example, level-1 headings could be 18-point
Helvetica bold with 12 picas preceding, while level-2 headings could be
14-point Helvetica bold with 6 picas preceding.  You can also vary heading
indents to provide hierarchical clues, too.  If you indent all text to, say,
12 picas from left margin, then you can place level-1 and level-2 heads
flush left and all subsequent headings at 12 picas.  (I pulled these numbers
out of my head.)  If you have any computer books on your shelf -- say, from
Que or SAMS or IDG -- open one and look at its layout as an example.

You can effectively implement cross-referencing by listing the section title
and the page it falls on, as in "See _How to Handle a Series_ on page 210."
Using section titles allows the reader to remember only the title's key
words but still find the right information.  Numbers require exact recall.
It's much harder to remember 3.5.1.2.4 than to remember "handle a series."
3.5.1.2.4 is an arbitrary label for information.  "Handle a series" is what
you want to *do* -- a concrete link to the information you seek.

I've never used FrameMaker, but I imagine it can be made to automatically
update cross references as text moves in the document.  (I used to do this
in Interleaf all the time, using an invisible automatic number sequence.
You can copy a pointer to an autonumber, paste it anywhere, and manipulate
the pointer to refer to the *page* where the autonumber appears.)

Peace,
jim

--
jim grey          |beebeebumbleandthestingersmottthehoopleraycharlessingers
jimgrey -at- iquest -dot- net|lonniemackandtwangin'eddiehere'smyringwe'regoingsteadyta
                  |http://www.iquest.net/~jimgrey

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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