[drupal-docs] Drupal Handbook Authoring Standards

[bryan on the web]

Okay, I made some changes to the document based on comments.  If you 
can view the Drupal page it is still:
http://drupal.org/node/15289

if not, here is a text version:
http://mysteryexperience.com/drupal/docs_guide.php

On Jan 7, 2005, at 8:03 PM, Richard Eriksson wrote:

> Just a note: I've had a proposed Drupal Documentation Style guide [1]
> which I'm following as best I can at Bryght's support documentation.
I added some info from your suggestions to the drupal.org page.  I 
guess I aggree with you that » is prettier than >, but that > is more 
standard and would work better in straight text documents.  I have 
ammended the guideline.


On Jan 8, 2005, at 3:26 AM, Dries Buytaert wrote
> 1. That page should be part of the "Documentation writer's guide", not
> part of the "About the handbook" section.
Done.

> 2. For consistency, the title should be "Drupal handbook authoring 
> guidelines" (not "Drupal Handbook Authoring Guidelines") or "Authoring 
> guidelines" for short.  Make that a guideline.
Oh, yeah.  Good point.  I added text about this, and changed the title.

> 4. Use relative links where possible.
I added something here.  See if you think this describes it the way you 
want it.

On Jan 8, 2005, at 4:48 AM, Boris Mann wrote:
> Yes, <h2> is the first that should be used in-page. However, h2 tags
> are currently styled identically to h1 [1], which makes it hard to
> read. Use h3 if you actually want it to look different.
This is where it would be useful to get input from Steve Wittens.  
Since he designed the theme for Drupal we should use his convention.  
On the homepage <h1> isn't used at all while <h2> seems to take it's 
place.  But on the handbook pages, article titles seem to be in <h1> 
but with a specific class.  The handbook author should not have to type 
in a special class.

<h3> Isn't very correct in the terms of structured markup since a 
heading title is really a 2nd level heading element.

<h2>More structured markup correct but does not give desired visual 
results on drupal.org with the current design.

On that note, I wonder if it would be possible to get a little spacing 
between <li> list items, again without a class or id tag required.  The 
lists on the documentation page look so stacked on top of each other.  
It would be better if they looked like the lists in the "Who's Online" 
block.