Documentation

Is there some Drupal documentation or a style guide which explains when to use what HTML markup?

For example, when to use <div class="section">, <div class="content">, <p>

• or when to use <h1>, <h2>, <h3>, etc.

• or when to use <div class="description">

I found the Drupal Markup Style Guide, http://groups.drupal.org/node/6355

^ which has some excellent "high level" guide lines - what I can't find is a catalog of Drupal classes and when to use them or what their purpose/meaning/rationale is

Does this exist?

There's a discussion going on about standards for documenting classes and interfaces in the Drupal API -- please comment on the issue (and NOT here) if interested:
http://drupal.org/node/718596

I've been toying with some questions surrounding our perpetual difficulty with docs, and our tendency to burn through docs contributors (perceived... maybe not actual).

This weekend in Seattle I met up with a few folks to talk about some larger documentation team issues which have come to light as a result of a tumultuous year for me personally, which caused me to withdraw from the community and my role as doc team lead. I realize that as the Drupal community has grown and changed, we have outgrown a model where one person alone can coordinate such a huge area as documentation. I asked several people, who had stepped in to fill leadership gaps and contacted me about general leadership concerns, to help me come up with a better plan for a sustainable doc team organization.

Based on various discussions over the last year, it seems that part of the solution involves improving the channels for communication and another part involves sharing leadership with as many people as possible. I feel that these changes will not only help us get docs back on track, but will make the documentation team stronger and more flexible as we head on down the road.

I've discussed this idea to some extent on the dev and docs mailing lists, it was suggested that I also post here. In brief:

I think it would be great if we (the broad Drupal community) could put together a series of online courses which teach people different aspects of Drupal.

The top priority in the Drupal documentation roadmap that was published earlier this summer was to reorganize the information architecture (IA) of the handbooks to make them easier to use and maintain. Becca Scollan volunteered to take the lead and she has been researching and building out a plan of attack. We are now at a good stage to start doing some work that the whole community can engage in.