Subheadings: Perhaps the Most Useful Technique in Technical Writing

My recent poll on why users can’t find answers in help material surfaced an interesting paradox. Consider these two reasons:

  1. The answer is buried in a long page, but the user only spends 2 minutes max on a page scanning.

  2. The help has been fragmented and dispersed over many small topics so the help is a maze.

In other words, help is either too long so users can’t find the answer, or help is too short so users can’t find the answer. Is this a paradox that is resolvable? Can something be both long and short at the same time?

I’ve talked about progressive disclosure and dropdown hotspots before, as well as long topics and short topics. I don’t want to rehash any of those same points. Onward I go into new territory!

Subheadings provide a solution to page length

Remember that my poll is what tech writers perceive to be reasons users can’t find answers in help, not what users actually think, or any objective measure of why users can’t find the answers (for that information, I would need to do real research, and as a blogger, I’m allowed free license to speculate).

Instead, I give you the easy answer to the problem of article length. What we simply need is a mechanism to facilitate scanning. Fortunately this mechanism has already been established — instead of long walls of text that are hard to scan, we break up information with subheadings. Subheadings are one of the most helpful and simple techniques for writing.

I actually only learned to love subheadings through blogging. I didn’t learn the subheading in college. For some reason, academics prefer long paragraphs and almost no subheadings (kind of like an imitation of the novels professors assign).

And my first technical writing job taught me to break up information into the table of contents feature in the sidebar, so that all hierarchy was a never-ending set of expandable and collapsable little sidebar folders.

It wasn’t until I started writing lengthy posts on my blog that I started really using subheadings — usually separating every couple of paragraphs with a new subheading.

Subheadings make it easy to expand content

Almost any Wikipedia page provides a great example of subheadings in action. There we have many paragraphs of content broken up by subheadings, with a built-in navigation embedded at the top. It’s a model that seems to work well on the web.

Why does Wikipedia use this structure? Wikipedia articles are often written by multiple people, who add information at different points of time. Not all the information fits neatly together into a coherent article. When you read a Wikipedia article, you’re not reading an essay in the New Yorker. You’re reading a lot of little sub-articles and sub-points about the same topic.

Technical writing has much more in common with Wikipedia than the New Yorker. We often have a laundry list of points to cover about a particular topic, and all those points don’t fit neatly into one coherent and flowing article.

Additionally, we often add the points over time, as new issues crop up, or as questions or problems arise. We need to suddenly bolt on some more information about “Widget X” because we find out more details about its use (such as incompatibility with a certain browser) and users need to know, so we add a new section (“Browser support for Widget X”). The new section doesn’t necessarily follow logically from the old one, nor does it have to.

Subheadings provide a way to easily expand the existing article in substantial ways, without worrying about clear transitions between the sections. The subheadings themselves are the transitions! It’s a lazy person’s style of writing because the order of the subsections themselves doesn’t often matter. They are like little children beneath a parent. The children can stand in a variety of orders, none particularly correct, because each subsection is an independent sub-thought.

And while the subheading method of organization may seem lazy, it actually supports the way people read technical material — by scanning and looking for specific answers.

Subheadings solve writer’s block

Subheadings also solve writer’s block. Have you ever opened a blank document and wondered where and how to begin writing? Subheadings make it easy to fill up a page. Instead of taking a stab at that first sentence and hoping you fall into a rhythmic flow of sentence after sentence, instead just make a laundry list of the points you want to cover. Group the points into main subheadings, which you list on the page. Then start filling in the spaces below the subheadings.

Subheadings are like the framing on a house. Once the frame is in place, you just fill in it in with insulation and drywall (the text). Try adding your insulation and drywall before you have a frame to hang them on, though, and you’re in for a real challenge.

Good subheadings describe the section clearly

Are there good subheadings versus bad subheadings? In general, a good subheading captures the point of the text below it clearly and succinctly, allowing readers to scan the list of subheadings to locate the information they want.

To continue with the previous example, “Browser support for Widget X” is much better than simply writing “Browsers.” And an even more specific subhead — “Internet Explorer doesn’t support Widget X” — might work even better.

Finding specific phrasing for subheadings brings us to another matter: parallelism. If your subheadings have parallel tenses, it will help readers scan them more easily. If some subheadings are phrases, some just words, others questions, action verbs, etc., it can be a bit jarring as readers scan down the page. On the other hand, avoid making any grammar decision that sacrifices clarity.

Also, using sentence casing (capitalizing only the first word) helps readers move their eye along the subheadings in a fast scanning motion, since sentence case is easier to read than title case capitalization.

Hierarchy in subheadings suggests meaning

The hierarchy with which you structure subheadings lets users understand meaning implicitly. By nesting one subheading under another, it lets the reader know the section is an extension of more detail from its parent section.

But when you start adding more than 3 levels of headings on the same page, the meaning expressed by this hierarchy gets somewhat lost. It’s harder for the user to keep track of which subheading level he or she is looking at.

Additionally, your CSS style needs to clearly distinguish between headings of different levels. Typically the title is h1, the main sections are h2, and any subsections are h3.

A good h2 level might be 18px font, h3 14px font. Additionally, Smashing Magazine’s research suggests you can switch the font-family between the subheading and its body. For example, use a sans-serif font like Helvetica for the subheading, and a serif font like Georgia for the body. But that doesn’t really matter (except to typography snobs).

Subheadings increase your page’s SEO

Headings also provide an easy way to increase the search engine optimization of your page (poor SEO was another problem in help that people noted in the survey).

Have you noticed how many times I’ve repeated the word “subheadings” in my subheadings? Not only does this keyword repetition help my SEO (for user’s searching for the word “subheading,” which might be unlikely), but the keyword appears in a heading element, which gets weighted more heavily in Google’s SEO algorithm. When you insert keywords into h1, h2, and h3 tags, they have more SEO weight than keywords that appear in the body of your article.

In general, you want to repeat the keyword or phrase about half a dozen times in the first sections on your page. Subheadings make repeating the keyword more natural and easygoing — you don’t even have to consciously think about SEO to do it well. Subheadings give you a space to be repetitive in a way that flows well on the page and ranks high in SEO.

Subheadings aren’t the only solution to scannability

Finally, subheadings aren’t the only way to help users scan large amounts of material on a page and find answers. By breaking up text with images, lists, block quotes, and other visual formatting, you allow the user’s eye to move quickly through information to find the answer.

With information that is centralized and easy to scan, few readers will complain that they can’t find the answer because it’s “buried” in text. And the more substantial length will provide a more complete context for the topic they’re reading about.

Additional Reading

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Hogwarts

    Subheadings are fine, but authoring in DITA really makes it more time consuming to create them than in any other application I’ve used. Essentially DITA encourages you to create a new file for each heading plus following content. Then you have to organize the subheading content. Boo DITA for being so author-unfriendly.

    • Larry Kunz

      Hi, Hogwarts. It’s good to know that DITA has found a home in the world of the wizards. Seriously, while I admit that it’s easy to get tripped up by the need to break big topics into smaller ones, I hope you won’t underestimate the usefulness of the element in DITA.

      • Larry Kunz

        Let’s try that again, without the actual symbols:

        ….I hope you won’t underestimate the usefulness of the SECTION element in DITA.

    • Ann Jackson

      If you use general topics in DITA instead of concepts, tasks, or reference topics, you can embed topics in the same DITA file. This is the best of all possible worlds from the point of view of sectioning but not having a gazillion files to deal with.
      The downside of SECTIONS is that they do not appear in the table of contents in the default DITA setup. Topics, whether standalone or embedded, do appear in the table of contents.

  • Mark Baker

    Subheadings are great. The next step is to define a standard set of subheadings for each content type so that authors do not have to invent the same pattern over and over again. Then you create a standard template to guide authors in creating content using those subheadings. And that is what structured writing is.

  • Peter Grainge

    A lesson from Information Mapping is to indent the text from the headings so that it is easier for the reader to scan through the headings. You may think the colour / size of the font would do that but try it with and without indentation. With indentation is easier as the brain is not having to tell the eye to ignore the body text, it is out of the line.

  • Larry Czaplyski

    Subheads work wonders in any type of writing including best-selling non-fiction, text-books, newspapers, magazine articles, copywriting, etc. They are a natural way to give the reader clues to what’s coming up next. They’ve been around since the flood, I think.

    They are as basic to non-fiction writing as paragraphs.

    In my opinion, hierarchy and structure, while important pale beneath the requirement that subheadings, as you say, be good and describe what’s coming clearly.

  • John Tait

    Subheadings are fine so long as you don’t subdivide further.

    Policy and procedure documents (that I work with) are often split again and again into complex hierarchies, have numbering (e.g. “ Process for change”), and are given complex GOTO cross-references. This approach makes any document far more complex to use than it needed to be.

    No two authors subdivide a document the same way.

    I don’t like DITA’s tiny task/reference/concept model at all, but DITA is an okay tool for writing longish articles with subheadings (using the section element) and building them up rather than dividing down. At least compared to using Word 2003.

    When given a choice, I more or less copy the STOP approach.

  • Laura Palmer

    ” For some reason, academics prefer long paragraphs and almost no subheadings (kind of like an imitation of the novels professors assign).”

    Actually, we don’t–if we’re academics with Tech Comm degrees. :) I agree that academics in writing-centric disciplines like history or literature do go for what I call “The Wall of Words”. They also love long sentences, strings of modifiers, and clever re-situations of subjects and verbs that nuance meaning.

    The above emulates a writing style that isn’t for a general readership and certainly not a readership that has to get something done (task). It’s for a readership that has both the fortitude and the time to read the same page three times with the goal of gleaning something new, interesting, or revelatory on each pass.

    But, in Tech Comm classes, we pretty much un-teach the writing students learn in composition classes, etc. All of a sudden, H1, H2 and even H3 are all over their pages. Sentences are constrained to a mandatory length; paragraphs are 3 to 5 sentences, max. Bullets abound. And vocabulary isn’t $50 words; rather, it’s what you’d find on the dollar menu.

    In other words, they learn how to make information accessible to the reader. And yes, I think every student should take an Intro to Tech Comm class in college.

    • Tom Johnson

      Laura, thanks for commenting. I’m glad to see that you’re teaching your students how to structure content with subheadings and other visual formatting. I actually never took a technical writing course when I was in college. In writing this post, I was mostly thinking back to my English literature courses, where professors constantly said a good paragraph took up about 2/3 of the page or more. They wanted to make sure I was *developing my ideas* with enough depth in each paragraph. Subheadings weren’t even mentioned.

  • Jonathan Price

    Tom, thanks so much for championing subheads.

    Why subheads?

    They’re key to making text scannable on screen.

    As you say, writing a blog definitely makes me aware of the need for a lot more subheads than we feel comfortable with when writing with the expectation that our work will appear on paper.

    BTW: I’ve explained my fondness for subheads on the web site for our book on web writing:

    • Tom Johnson

      Jonathan, thanks for sharing the link. It’s great to see more treatment of subheads. I think some of these more fundamental writing principles get overlooked so easily in tech writing discussions.

  • Tom Johnson

    Here’s a related article about subheadings that is much more visually appealing:

  • jay maechtlen

    Good grief – now subheads are a new idea?
    ISTR a concept – “outline”
    Yeah, we shouldn’t use too many levels – “too many” depending on subject requirements.
    The structure and heading levels help the user understand the relationships between one concept/topic and another.

    oh, well – the old becomes new again…

    • Tom Johnson

      Jay, thanks for commenting. Of course subheads aren’t a new idea, but I never said they were. Every blog post doesn’t introduce a new idea, but I wanted to elaborate on subheadings with more detail and insight, since I think they solve many problems in content organization.