Two powerful words for your help content: “For example”

Debates abound about what kinds of content should go into software documentation. But something that is rarely discussed is the use of examples. That’s unfortunate, because examples are one of the most effective tools that a technical writer can use.

Examples have a way of simplifying ideas. They can convey information more quickly and more directly than many words of explanation. And they liven up your content.

Let’s explore a few ways that you can use examples, and why your readers will appreciate them, through the mental model of the “ladder of abstraction”.

The ladder of abstraction

I first read about this concept in a book called Language in Thought and Action by S.I. Hayakawa.

In his book, Hayakawa shows that at every level of abstraction in the ways we communicate, both the reasoning and language that we use changes. The concept applies widely, and can go deep into linguistics and communication theory, but I like to apply it in the realm of written examples.

To demonstrate the ladder, Hayakawa introduces a cow named Bessie. To the farmer or perhaps to a farm visitor, Bessie is a friendly individual animal that we might pet or feed some hay to. But the farmer might also consider Bessie to be just one member of a herd of livestock. From a higher perspective, Bessie might be discussed as a farm asset, or part of a family’s livelihood. Even part of a nation’s agricultural wealth. As we go up the ladder, the concepts and the language get more abstract and we lose track of specific details about Bessie.

So what does this have to do with examples? As we go up and down the ladder, we move from the abstract (at the top) to the concrete and tangible (at the bottom). The language used at each level can appeal to a different type of reader, but the more concrete and tangible language near the bottom of the ladder is usually grasped more immediately by more readers.

And that’s the magic of examples: they can readily take an abstract concept and make it understandable.

Ways of including examples

I like to categorize examples into three broad types:

• inline examples
• short examples
• long scenarios and tutorials

We’ll look at these types in the context of examples from the Shopify Help Center. Many entrepreneurs and business owners use Shopify to create an online store to sell their goods. The platform handles various aspects of their business, such as inventory, orders, and shipping. The Help Center provides instructional content to learn about ecommerce and how to use Shopify.

Inline examples

You can subtly work examples into sentences by using the phrase “for example” or similar phrases, including “such as” and “like”. You often don’t even need to include these phrases.

In one topic of the Help Center, we introduce the concept of “locations”:

The first line introduces the term “locations” and gives a purpose for them, but is still pretty abstract. The second line, however, makes the concept concrete to a business owner by using terms they are readily familiar with: retail stores, warehouses, and other places where they store their inventory.

Another topic has the following short sentence that explains the concept of digital products. It shows the use of “such as”:

The “such as an MP3 or PDF” phrase could have been left out, but then readers would have to mentally map the notion of a digital product into something more tangible. By mentioning examples of specific types of digital products, the content does the work for the reader.

Short examples

These types of examples are often called out with a heading that uses the word “Example”. By including the word in the heading, the example is more readily seen by anyone skimming a topic. Links to the example might also appear in sitemaps, sidebars, and other navigation aids.

Although the example might be only a few lines long, you can add interest and hints of a story in your short examples.

In a topic on stock keeping unit (SKU) formats, our Help Center describes how these codes are used by a business. Let’s say that the introductory description is halfway up the ladder of abstraction. The topic then gives a couple of tangible short examples, including this one, to get further down the ladder:

The text refers to an individual (Juanita) to make it more personal and relatable. It refers to an apparel store, which is lower on the ladder than a generic store that sells some abstract product. This short example also uses an embedded inline example to go even lower on the ladder, showing the format of a specific instance of a SKU for a particular type of pants.

Long scenarios and tutorials

You can also take your reader into comprehensive concrete examples if you build out a longer scenario or even a complete tutorial.

For instance, one of the areas of Shopify that can be a little hard to understand at first is how to filter sales reports. This feature allows a business owner to generate reports of their sales over any date range, and then they can narrow down the report to show, for example, only the sales from their online store, filtering out their retail (in-person) store sales.

Each business owner might have unique ways of how they want to filter their reports, so the filtering feature is rich with options. And the design of the feature uses some logic mechanisms for including some sales and excluding others. As a result, the user interactions can get a bit intricate.

To help business owners with this feature, we created a longer example with detailed steps and screenshots to show how to filter the report in one particular way. (You can take a look at the example on the site.) This type of example goes very low on the abstraction ladder, and can be of great use to some readers. However, this also exposes the danger of getting too specific in examples.

These types of longer examples take more effort to create, take up a fair amount of screen real estate, and have a greater maintenance overhead. And a detailed example might be relevant to a relatively small number of readers. Used in the right context, long examples are effective and fun to create, as long as they’re created carefully.

Create your examples with care

Examples are good additions to your help content, but you do have to keep a few considerations in mind:

• Avoid trivial examples. If you need to tell a user to enter a country name in an address field, it’s not particularly helpful to add the line “For example, enter United States.” Trivial examples add word count without adding any value.
• Avoid obscure examples. In the Shopify Help Center, if we want to mention a type of store as an example, we could mention a children’s shoe store that specializes in rainbow glitter-covered Mary Janes. But because that is relatable to such a small segment of readers (it’s too low on the ladder of abstraction), just mentioning an athletic shoe store will be more useful to more readers.
• Don’t overdo it. Examples can be used often, but shouldn’t be used too liberally. Include them when you need to clarify abstract ideas. But if you include too many examples, your content could become unfocused and more difficult to read.
• Try going up the ladder. You can include examples to help explain a detailed topic by going up the ladder of abstraction. For example, you can give some business context when discussing a specific feature of a product to show how and where the feature might be most useful.

Think of the ladder and benefit your readers

Try including more examples in the next set of content that you work on. If you don’t already use any, perhaps start with some inline examples, since they tend to be short and might be the easiest to come up with.

And think about how you can add examples in contexts well beyond help content. Whether you’re writing technical articles, internal-facing procedures, or blog posts, examples can be a powerful way of taking your complex ideas and concepts from the abstract to the tangible.

Thanks to my colleagues Angela Counter and Rory Tanner for their helpful edits and suggestions.