[placeholder]

Part 2: Use Good Headings For Structure And Scanning

Part 2: Use Good Headings For Structure And Scanning

This is Part 2 of a five part tutorial on technical writing. To learn why this tutorial is the way it is, and why technical writing in general, see the Intro post then Part 1.


KEY TERMS

  • In this tutorial, an app represents a single piece of software that’s provided for others to use. This could be a mobile app, a web app, a microservice, a database, an API, a Figma component library, a React component library, a script, and so forth.

  • Any piece of writing that includes technical writing.

  • Abbreviation for table of contents.

Part 1 of this tutorial introduced you to the content types that are most common in technical documentation. You also evaluated a real-life example as a reader, and you may have realized how headings are essential to a good reader experience. It’s because readers on the web do not read – they scan¹ . People actually read 25% slower on the web² and they only read 20% of the content on a page³. (This data is from 2008; I’m scared to know the percentage today.)

Headings in technical documentation serve as a blueprint and a map. Organizing headings is known as content structure, and headings are often used to auto-generate a TOC, which readers typically scan to understand the topics in the documentation.

GOOD HEADINGS + GOOD STRUCTURE = EASY-TO-SCAN

This equation is true no matter if the page is displayed in something like Google Docs, on a feature rich website, or on a mobile device. Even your experience reading this post would be very different if I didn’t use helpful h1, h2, and h3 headings.

Because I’m constantly reading new technical documentation to become a better writer (hint, hint), over the years I’ve noticed some common headings. These headings can be used for different content types, and tend to be much more helpful for readers. For example, “At a glance”. Organizing headings is specific to the content type and the reader’s goal, which you’ll see in the cheat sheets.

For each content type, I’ve listed common headings and various options to structure them in the cheat sheet (headings specific to the app are underlined). I haven’t included options for Onboarding guides and Runbooks since the documentation format and content is team specific.

Getting started guide

Most getting started guides are titled as “Get started” or “Quickstart”. And because the word ‘start’ is in the title, a reader is expecting to get started with the app by the end of the guide. The structure and headings in getting started guides should ensure that the reader accomplishes this goal. If not, a reader may become confused, and give up working with the app.

A getting started guide shouldn’t have more than five numbered steps. If the process itself is complex, some apps have a “Get started tutorial”. See IBM and Figma as examples.

See the cheat sheet for a getting started guide.

Tutorial

Tutorials are short lessons; they’re not fully flushed training courses. Most tutorials help the reader learn by doing; but some demo a concept, say “state management”.

See the cheat sheet for a tutorial.

How-to guide

The headings for how-to guides are more varied because the task is specific to the app. However, the general content structure often looks something like the one in the cheat sheet.

See the cheat sheet for a how-to guide.

Explanation guide

Because concepts vary from app to app, I haven’t seen many common headings for explanation guides. However, as a writer, I tend to use questions as headings (such as “What is a component?”) when I need to clarify something about an app.

The structure of headings in explanation guides tends to feel like a funnel, the first is usually very broad, the second less broad, and so on. By the end, many explanation guides link to relevant guides such as how-tos and tutorials, or even a get started guide.

See the cheat sheet for an explanation guide.

Reference guide

Most reference guides mirror the structure of the software element itself. For example, a reference guide for a Java library may have headings like “Classes”, “Methods”, “Fields”. However, as a reader, I always find examples with different specifications more helpful than details. This is why I listed Examples near the top of the general structure in the cheat sheet.

On that note, after much research on my part, I included a general structure for reference guides in the cheat sheet. The list of common headings was becoming pretty long when even a simple app has an extensive list of software elements. The general structure should work well for most elements like endpoints, components, commands, and such.

See the cheat sheet for a reference guide.

Troubleshooting guide

As a reader, I’ve seen (and used) Troubleshooting guides structured like the one in the cheat sheet. I’m sure there are others, but I just haven’t discovered them yet.

See the cheat sheet for a troubleshooting guide.

Try it out

For your content type, create headings that are helpful to your readers. Use the cheat sheet if it’s helpful. Some tips to keep in mind:

  • If a heading from a different content type resonates with you, feel free to use it!

  • If you need to create custom headings, try to create ones that are a little more descriptive than not.

  • Organize the headings so it feels natural to your reader and how they’ll consume the information.

Up next

Part 3: Draft content that’s accurate, consistent, and concise. This part introduces glossaries and how they help you keep your content more consistent. For concise content, guidelines are provided in a cheat sheet for each type of technical documentation.


¹ See Why Web Users Scan Instead of Reading from Nielsen Norman Group; this group has researched user experience on the web from the early, early days. Another great article on the topic by the same group.

² See Be Succinct! (Writing for the Web) from Nielsen Norman Group.

³ See How Little Do Users Read? from Nielsen Norman Group.

Part 3: Draft Content That’s Accurate, Consistent, And Concise

Part 3: Draft Content That’s Accurate, Consistent, And Concise

Part 1: Learn The Different Types Of Technical Documentation

Part 1: Learn The Different Types Of Technical Documentation