Re: How many levels of indents and heads are reasonable?

[Yves JEAUROND <jingting -at- rogers -dot- com>]

Last Tier?
  To reduce the number of indents, not every topic has to be numbered ( gasp! ). The topics in the last tier (or indent) of your structure can use a "definition style" for short, highly structured expository topics. It creates a ghost of an indent. If they are a bit longer, adding a subhead might even be sufficient. It also informs the reader that there are no more numbered indents.
   
  Another is to remove the First Level and make it a chapter heading. 
   
  The simpler, the better???
   
  To reuse John Posada's excellent example for the last tier. 
  1.0 Databases
1.1 Database1
     1.1.1 Overview
     1.1.2 Specifications
               Permission. [subhead or definition & procedure]  // no numbering
               Attributes. [ " ]
               Stored Procedures [ " ]
               Triggers [ " ]
               Indexes [ " ]
               Replication [ " ]
1.2 Database2
     1.2.1 Overview
     1.2.2 Specifications
               Permission [see above]
               Attributes [ " ]
                 Stored Procedures [ " ]
               Triggers [ " ]
               Indexes [ " ]
               Replication [ " ]
1.3 Database2
     1.3.1 Overview
And so on...
   
  Removing the first tier
  Databases
1 Database1
     1.1 Overview
     1.2 Specifications
               Permission. [subhead or definition & procedure]  // no numbering
               Attributes. [ " ]
               Stored Procedures [ " ]
               Triggers [ " ]
               Indexes [ " ]
               Replication [ " ]
2 Database2
     2.1 Overview
     2.2 Specifications
               Permission [see above]
               Attributes [ " ]
                 Stored Procedures [ " ]
               Triggers [ " ]
               Indexes [ " ]
               Replication [ " ]
3 Database2
     3.1 Overview
And so on...
   
  Regards,
   
  YJ

John Posada <jposada01 -at- yahoo -dot- com> a écrit :
  > Asking how many levels of indents and heads are reasonable 
> is asking how big of a system is it reasonable to document. 

I don't agree. I propose that you can define the number of levels you want to stay within, then structure your documentation to fit within that definition (and I think this is pretty much a mandatory definition when you are defining your DITA schema). 

Take the two examples...I've picked the subject of databases because in an enterprise system, databases and their documentation can be huge:

1.0 Database
1.1 Database1
1.1.1 Overview
1.1.2 Specifications
1.1.2.1 Permission
1.1.2.2 Attributes
1.1.2.3 Stored Procedues
1.1.2.4 Triggers
1.1.2.5 Indexes
1.1.2.6 Replication
1.2 Database2
1.2.1 Overview
1.2.2 Specifications
1.2.2.1 Permission
1.2.2.2 Attributes
1.2.2.3 Stored Procedues
1.2.2.4 Triggers
1.2.2.5 Indexes
1.2.2.6 Replication

or

1.0 Database Model
1.1 Database1
1.1.1 Overview
1.1.2 Permissions
1.1.3 Atrributes
1.1.4 Triggers
1.1.5 Indexes
1.2 Database1
1.2.1 Overview
1.2.2 Permissions
1.2.3 Atrributes
1.2.4 Triggers
1.2.5 Indexes
2.0 Database Replication
2.1 Database1
2.2 Database2

Granted...this was an example off the top of my head, it was a simple, and it only eliminated 1 level. However, in my opinion, the levels of any document set can be kept to a minimum...just takes some thought and effort.

John Posada
Senior Technical Writer

"They say everyone needs goals. Mine is to live forever.
So far, so good."
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 jingting -at- rogers -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/jingting%40rogers.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.


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

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.