[drupal-docs] Styleguide

[Dries Buytaert]

On 25 Apr 2005, at 13:16, Moshe Weitzman wrote:
> i wonder if someone would make these statements after writing a bunch 
> of book pages. The statements sounds nice, but are impractical. We 
> *should* to provide some approved way for authors to add structure 
> within a single page. And a list does not always satisfy this need. To 
> describe all but the most simple concepts, you want structure.
>
> If we force authors to create subpages every time they want structure 
> we will not end of with "smaller, flatter nodes which are easier to 
> read and navigate". We will end up with deep, annoying hierarchies 
> where it takes 7 clicks to get to the damn URL for the Contrib 
> repository (e.g Handbook => Contributors Guide =>  Development => CVS 
> => Repositories => Contributions => Configuration). Another example 
> might be a page like http://drupal.org/node/12352. We should not 
> recommend that authors break up such a page into many subpages, IMO

I agree with Moshe that more nodes isn't the solution.  The goal should 
be to have less book pages, or at least, less clicks.  As a rule of 
thumb, the book's navigation structure shouldn't get any deeper than 3 
or 4 levels.  We should add that to the style guide and reorganize the 
sections that violate this rule.

At the same time, I agree with puregin that 'rewriting' header tags is 
a bit of a kludge.

--
Dries Buytaert  ::  http://www.buytaert.net/