Subheadings: Perhaps the Most Useful Technique in Technical Writing

by Tom Johnson on Aug 23, 2013
categories: findability

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

• How to Increase Content Findability on Your Web Page
• Inserting Meaningful Headlines and Subheads