[development] Documenting contribs

[Thomas Barregren]

Derek Wright wrote:
> while we're at it, can we fix another annoying problem: use of <h2> 
> tags in project teasers makes the download pages really confusing.  
> for example, check out:
>
> http://drupal.org/project/opensearchclient
>
> looks reasonable, since the "OpenSearch Client" part is visually 
> distinct from all the headers.
>
> now, go to: http://drupal.org/project/Modules and search for 
> "OpenSearch Client".
>
> it's *really* confusing, since all those <h2> headings are the same as 
> the module names.
>
>
> a) seems like we don't need that much info in the project teaser, 
> anyway, and you shouldn't need any <h*> tags to organize your teaser
>
> b) i could change theme_project_summary() to do something other than 
> an <h2> for the project titles in these summary pages.  however, by 
> convention, it seems like we use an <h2> as the title when displaying 
> a list of nodes.
>
> thoughts?

I agree.

a) A teaser should not be any more than just that: a teaser. The purpose 
with a teaser is to puff for the actually content.

b) Of course headings should be h3. Why not remove h1 and h2 from the 
input filter?

Regards,
Thomas