[drupal-docs] Styleguide

[bryan kennedy]

On Apr 25, 2005, at 6:16 AM, 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.

Agreed.  Not using heading tags is silly.  It would be very hard to 
actually author any of the handbook without them.  The Handbook isn't 
one big HTML document.  If it was I would see purgin's point.  Yes, the 
handbook provides structure but so does the internal HTML.

On Apr 25, 2005, at 1:09 AM, puregin wrote:

>      Yes, that one puzzled me.   There's a couple of pages where 
> 'Drupal' or 'Handbook'
> might be removed, but most of the occurrences seem fine as they are.  
> It's tough to
> write about something if you can't mention its name.

Keep in mind that a guideline doesn't need to be currently violated to 
be a good guideline.  The problem was that tons of the the handbook 
pages had/have titles like:

Drupal's Page Serving Mechanism
Drupal's node building mechanism
Drupal Plain PHP themes
Drupal Theming Oveview

The Drupal was and is redundant.  Forgive me, I kinda just made up the 
last two but they were there.  I did a bunch of title editing a while 
back.

On Apr 25, 2005, at 8:58 AM, Charlie Lowe wrote:

> "Use short descriptive titles to label your handbook entry. Avoid 
> redundancy; it is not typically necessary to use the word Drupal or 
> Handbook in your title since you are already obviously talking about 
> Drupal and your documentation is already obviously a part of the 
> Handbook."
Awesome, looks good to me.

The next step is to incorporate this document into the workflow.  We 
should check against it when people want to post a new handbook page.

bryan