TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Re: Numbered versus unnumbered heads in very technical reference guides
Subject:Re: Numbered versus unnumbered heads in very technical reference guides From:Julie Stickler <jstickler -at- gmail -dot- com> To:tech2wr-l <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 18 Jun 2013 17:49:44 -0400
By all that is holy, if you're going to number headings (and I can
appreciate Fred's argument for numbers), limit the number of levels that
you have! At my last job we had numbered headings that went six, seven,
eight levels deep. I think I might have found one section that went to nine
levels. And it was not pretty.
On Tue, Jun 18, 2013 at 5:38 PM, Fred Ridder <docudoc -at- hotmail -dot- com> wrote:
> Leonard Porello wrote:
>
> > Do you number down to the individual paragraph level? If not, how far
> down do you recommend for your purposes?
> >
> > -----Original Message-----
> > From: techwr-l-bounces+lporrello=illumina -dot- com -at- lists -dot- techwr-l -dot- com[mailto:
> techwr-l-bounces+lporrello=illumina -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of
> Fred Ridder
> > Sent: Tuesday, June 18, 2013 2:18 PM
> > To: Julie Stickler; tech2wr-l
> > Subject: RE: Numbered versus unnumbered heads in very technical
> reference guides
> >
> > It's much easier, faster, and much less ambiguous to point the customer
> to Section 6.3.2 than to try to direct them to the third paragraph on page
> 89 or to the "Things to watch out for" subsection under the "Configuration
> options" section in the "Frumious interface" chapter.
>
>
> I do not number down to the individual paragraph level. I number headings
> rather than content paragraphs, so the real issue is how many levels of
> headings.
>
> My personal preferences is to stick to 3-4 levels of headings (plus an
> unnumbered "utility" heading that looks like a level 4 without the numbers
> and that does not show up in the ToC). When I encounter a document that
> has 5 or 6 (or even 7) levels of numbered headings I start looking to see
> whether the number of levels can be reduced. Sometimes one or more of the
> top-level divisions (chapters) cover too broad a subject and should be
> divided. Sometimes the problem is on the other end, with topics being
> divided with too fine a granularity (if you've got a series of headings
> with only one paragraph each, you should probably convert to a list with
> run-in heads, for example). And sometimes the problem is "do-nothing"
> headings in the middle of the hierarchy in some chapters. There have been
> cases where I've had to live with 5th-level headings in a few chapters, and
> one particularly complex interface specification where 6 levels were
> unavoidable, but 4 levels or fewer keeps me happy.
>
> -Fred Ridder
>
>
>
--
Julie Stickler http://heratech.wordpress.com/
Blogging about Agile and technical writing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
