OT: Heading levels in a UG

[Andy Kass]

Very interesting topic, and quite a funny anecdote about ET pigeonholing tech writers. We have 4 levels in our templates, including the chapter title, but usually avoid going down to 4. So most content is under

1 Chapter Title (actually a Heading 1)
1.2 Heading 2
1.2.3 Heading 3

For our type of doc (user and admin guide for GUI-based application), this really covers it. We find that if we have smaller pieces, we put them together in a bulleted list with lead-ins (* Lead-in - Text...) or in a table. Both easily support 1-3 paragraphs per item and provide a way of grouping similar information (button functionality, etc.). One thing we do is flatten some levels, when the logical distinction between them is not important. You can also refactor the lower levels to a higher level especially if it is more in line with use cases. To illustrate both techniques:

1. Administration                  VS 1. Administration with the GUI
1.1 User Management                   1.1 Creating Users
1.1.1 Creating Users                  1.2 Deleting Users
1.1.1.1 Creating Users with the GUI   1.3 Creating Roles
1.1.1.2 Creating Users with the CLI   1.4 Creating Roles
1.1.2 Deleting Users                  
1.1.2.1 Deleting Users with the GUI   2. Administration with the CLI
1.1.2.1 Deleting Users with the CLI   2.1 Creating Users
1.2 Role Management                   2.2 Deleting Users
1.2.1 Creating Roles                  2.3 Creating Roles
1.1.2.1 Creating Roles with the GUI   1.4 Creating Roles
1.1.2.1 Creating Roles with the CLI
1.2.2 Deleting Roles
1.1.2.1 Deleting Roles with the GUI                  
1.1.2.1 Deleting Roles with the CLI

We do use heading 4s for really big chunks of subordinate matter. For reference docs, sometimes the extra levels are unavoidable due to the complexity and levels in the product itself.

  Andy

akass at jaspersoft.com

Original message:

On Wed, Jul 15, 2009 at 7:31 AM, Lin Sims<ljsims.ml at gmail.com> wrote:
> On Wed, Jul 15, 2009 at 3:25 AM, Evanth,
> Henrik<Henrik.Evanth at sonyericsson.com> wrote:
>> Hi All
>>
>> I have an off-topic question that may or may not interest you.
>>
>> We are having a discussion at the office regarding the maximum levels of heading that a User guide/User manual can/should contain. Do you know of any best practice rules that define how deep a publication should/could be. Personally I think that 6 levels is too deep for a user, but that is just a personal preference that I cannot back up with "evidence".
>>
>> Heading 1
>> ? Heading 2
>> ? ? ?Heading 3
>> ? ? ? ? Heading 4
>> ? ? ? ? ? ?Heading 5
>> ? ? ? ? ? ? ? Heading 6
>>
>> Insights, comments or instructions are highly appreciated.
>
> I attended an Edward Tufte seminar a number of years ago. He does book
> signings at these, and while he was signing my copies he asked my
> profession. When I said "technical writer", his response was "No more
> than 3 levels of headings."
>
> --
> Lin Sims
> _______________________________________________


Art Campbell says it this way:

"I agree, four is as many as you need (and, I believe the most I've
ever seen in a published book) -- if you think you need more, it may
be because of an organizational problem."

I guess Tufte didn't verbally indicate "*" and "<G>" with his comment.
His methods of providing multiple layers of information - sparklines,
common measurement references across graphics that vary in scale, and
various graphic schemes that indicate data and information
relationships - present much of the additional levels of information,
without additional heading levels. IOW, "organizational problem"
solutions.

Regards,

Peter
__________________
Peter Gold
KnowHow ProServices