RE: Numbered versus unnumbered heads in very technical reference guides

Subject: RE: Numbered versus unnumbered heads in very technical reference guides
From: Fred Ridder <docudoc -at- hotmail -dot- com>
To: "Porrello, Leonard" <lporrello -at- illumina -dot- com>, Julie Stickler <jstickler -at- gmail -dot- com>, tech2wr-l <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 18 Jun 2013 17:38:05 -0400

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



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

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

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
RE: Use if xrefs in topic based or minimalist writing: From: Porrello, Leonard
Numbered versus unnumbered heads in very technical reference guides: From: Matt Gras
RE: Numbered versus unnumbered heads in very technical reference guides: From: Erika Yanovich
Re: Numbered versus unnumbered heads in very technical reference guides: From: Julie Stickler
RE: Numbered versus unnumbered heads in very technical reference guides: From: Fred Ridder
RE: Numbered versus unnumbered heads in very technical reference guides: From: Porrello, Leonard

Previous by Author: RE: Numbered versus unnumbered heads in very technical reference guides
Next by Author: Re: Contract rates
Previous by Thread: RE: Numbered versus unnumbered heads in very technical reference guides
Next by Thread: Re: Numbered versus unnumbered heads in very technical reference guides


What this post helpful? Share it with friends and colleagues:


Sponsored Ads