Re: opinion on outline numbering for chapters/sections

[Keith Hood <klhra -at- yahoo -dot- com>]

I suggest putting the Quick Start thing at the back as an annex, and put in a TOC entry that shows the page it starts on. That way you don't have to worry about its numbering scheme meshing with the outline numbering in the rest of the document. That makes it easier to create sensible outline numbering in both the QS and the main body of the doc. If you make it an annex, I would recommend that somewhere in the main body you put an "About the Quick Start" section that gives a quick overview - not a TOC - of the QS contents.



I think having numbering like this:

2.2.1.1  A)    
2.2.1.2  B) 

is even more confusing. The presence of 2.2.1.1 A) implies that there is a 2.2.1.1 B). 

And, the presence of 2.2.1.1 B) implies that it should be led by 2.2.1.1 A).  

I'm pretty sure this kind of numbering will make some people think that some content is missing.

If it was my project, I would do everything I could to restrict the number of heading levels to no more than three. More than three levels in the TOC, and it becomes confusing to the reader and people are more likely to lose their place. (This is, of course, assuming a relatively low level of reader capability, which is often a good idea.) That 3-level rule forces me to think really long and hard about how the content should really be organized. Sometimes you just have to give up and go more than three levels deep, but in my experience that doesn't happen very often. 


--- On Wed, 6/11/08, Gina Jones <gina -dot- techwriter -at- gmail -dot- com> wrote:

> From: Gina Jones <gina -dot- techwriter -at- gmail -dot- com>
> Subject: opinion on outline numbering for chapters/sections
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Date: Wednesday, June 11, 2008, 1:59 PM
> Hey Everyone,
> 
> I'm normally a lurker. I benefit from this list and
> thank all of you for
> your participation.
> 
> I need some opinions on my numbering sequence in a User
> Guide. My client
> specifically requested that I embed the Quick Start into
> the manual and
> provide more details. I'm not a fan of outline
> numbering in user guides, but
> must follow their corporate style guide. Below is this
> particular numbering
> sequence.
> *
> 2.2***    Software Quick Start
>   2.2.1    Set Up Software Web Appliance
>     2.2.1.1  A) Configure the Web Appliance
>                  <Step/Action table here>
>                   1
>                    2 a)
>                       b)
>                       c)
>                       d)
>                       e)
>                       f)
>     2.2.1.2  B) Configure the Analyzers
>                  <Step/Action table here>
>                   1
>                    2
>     2.2.1.3  C) Connect the Switch to the Analyzers
>                  <Step/Action table here>
>                   1
>                    2
>     2.2.1.4  D) Connect the Ethernet.
> 
>     2.2.1.5  E) Access the Web Application.
>                 <Step/Action table here>
>                   1
>                    2
> 
>   2.2.2  Set up Downstream Monitoring
> 
> 
> Once I get to 2.2.1.1 I feel that the instructions become
> confusing, so I
> put A), B), C), etc. at the beginning of the headings since
> they are part of
> the sequence of steps. However, now I'm thinking that
> it makes it more
> confusing. What do you think?



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

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
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-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

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