The handbook style guide says that heading tags should never be used on handbook pages.

I've broken this rule once, hoping not to get caught :-) and now I find that I want to do it again, so I guess I'd better start a discussion on it. I suggest we change this handbook page to say "almost never".

I get the reasons given in the style guide, I really do. But I also feel that there are exeptions.

http://drupal.org/node/254214 is an overview of a big and complex subject which has handbook pages and resources in lots of different places. As an overview, it should be one page -- that makes it easy to scan and find what you're looking for. But it describes different aspects of the subject -- both structurally and readability-wise the sub-headings make sense.

http://drupal.org/node/296338 is more border line. It can do without the headings, but it does (or will) consist of three distinct parts:
- A brief intro (what is this and why should you do it)
- The main part: How to do it
- A list of links to more information

All those three parts need to be on the same landing page. The page will work better if the middle part stands clearly out from the rest. And since it consist, quite logically, of three subchapters, it makes a lot more sense (and is structurally sounder) if I use subheadings to separate the parts than if I try to be fancy with formatting.

http://drupal.org/node/208456 is another example of a page which would be more readable with sub-headings within the page -- there are a lot of short module reviews, each one so short that using sub pages would make it a lot more of a hassle to read. That page uses <strong> for each review. <h2> or <h3> would make more sense.

Comments

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

Hello, my name is webchick, and I'm a heading-o-holic.

Long ago I learned to ignore this page because I thought it was a stupid rule. Now I read it again and realize it's a stupid page as well. ;)

This page seems to date from back when a few things were the case:

  1. Book module had the ability to export Docbook XML, and headings would get it all confused as to where chapters began and ended. This functionality was stripped out in 4.7, I think.
  2. We had a general guideline of each book page being no longer than a single screen-full of information. If it was longer than that, it should be a sub-page. This may have worked fine when there were only a couple hundred handbook pages (I was able to read the entire handbook cover-to-cover in a day back when I first started), but there are a few thousand now, and the scope of what's covered in the handbook has dramatically ballooned as well.
  3. We had more developers than newbies in our community, who learn tricks like clicking the "Printer-friendly version" link gets you a single page with a book and all its sub-pages for easy readability. Newbies do not know this, and they cling to documentation like a Bible. It is far less tedious to learn about a topic if it's all on one page (within reason, of course) than if it's spread across 1500 sub-pages. I use http://drupal.org/handbook/cvs/quickstart as a flagrant example of a page that would totally suck if it were done according to the specs in that book page.

However, something we do need guidelines on is what headings to use when you use them. For example, you should never use a <h1> tag in a handbook page, since that is the title of the page. I'd also argue you should never have to go further than <h3>. If you find yourself doing <h6>, then you probably should indeed be breaking things out into other pages.

add1sun’s picture

add1sun commented
Category: support » task

I agree that "no headings" is silly. I propose that we rewrite the Avoid heading tags in Handbook pages to be Headline Use Guidelines (or some better name). We can lay out that h1 should never be used and that h2 and h3 should be used as section headers instead of just bolding (maybe explain what the strong tag should be used for) and that if a page feels like it needs h4 or higher that you should split the page up.

Moving to "task" since three docs team members agree.

dnewkerk’s picture

dnewkerk commented

Thanks for posting about this... as I'm the process of writing a pretty lengthy guide for docs, I ran into the same issue myself. I've broken down my HowTo into 3 main top-level sections, and in those I've broken the "major steps" into sub-pages. However on the pages themselves, I've used h2 and h3 tags to help visually organize the information. I was a bit disturbed to think of how many pages I'd need to break things into if I were to follow the Heading guidelines which I noticed just the other day. If necessary I'd be glad to break it down more than it currently is, but to bar Heading use entirely seemed pretty ridiculous to me (especially in light of proper semantics and accessibility considerations). With a guide as in-depth as the one I'm writing, the hierarchy could become 4-5+ levels deep if headings are not used.

Here's my article in case anyone has a moment to look: Creating a CCK and Views powered Drupal site
(the title is tentative, guide is also not fully complete yet... also yes I know I've got 1-2 style guide issues to fix... if my heading use is inappropriate feel free to let me know)

+1 on a revision of the Heading tags guidelines

I agree h1 is a big no-no (should only ever be one h1 tag on any page). I always begin my headings at h2 and have never needed to pass h3.

Thanks!

- David

add1sun’s picture

add1sun commented
Title: Handbook style guide: "Never use heading tags". Never? » Update Style guide re: using headings

Changing title to reflect what needs to happen. :-)

nielsbom’s picture

nielsbom commented
Component: Misc » Other documentation issues

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443
-nielsbom

betz’s picture

betz commented
Project: Documentation » Drupal core
Version: » 7.x-dev
Component: Other documentation issues » documentation
jlin’s picture

jlin commented
Assigned: Unassigned » jlin

I think what's been proposed makes sense, and I personally prefer longer reading lengths with appropriately marked headings. I'll take a stab at this. First, I'll edit http://drupal.org/node/24221 and when it's ready, I want to put it into the main Handbook style guide as they clearly belong together.

Probably can finish this by the end of the week. Don't have much free time, but I'll try.

It's my first issue, be gentle if I mess up!

add1sun’s picture

add1sun commented
Project: Drupal core » Documentation
Version: 7.x-dev »
Component: documentation » Correction/Clarification

Hm, this got moved to the wrong queue. Movng back to docs.

leehunter’s picture

leehunter commented
Status: Active » Fixed

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.