Examples Are a Primary Way That Complicated Concepts Become Clear

by Tom Johnson on Aug 20, 2013
categories: findability

In my recent poll about why users can't find the answer to help, one of the top answers (so far) is the lack of examples:

The help doesn't provide concrete examples that make the concepts understandable.

(View total votes.)

I've long been a fan of examples in help documentation, but I didn't suspect they played such a large role. In fact, one rarely hears any presentations or reads blog posts on using examples. It's time to give this technique its 15 minutes of fame.

Parallels with Creative Writing

Let's start with a parallel. One of the first principles of creative writing is to use concrete details rather than abstract ideas. In your novel, instead of writing, "He loved her with a deep yearning," you might say, "He waited at her bedside in the hospital every day for 3 weeks while she was in a coma, hoping she would wake."

Concrete, specific examples clarify abstract ideas in powerful ways. As writers, we know this. In tech writing, we may not be trying to clarify abstract emotions, but we're certainly trying to clarify abstract features, workflows, and concepts. It's not always clear how a particular technical feature might be used or implemented.

Examples help clarify the feature and bring it into focus. In fact, the more confusing something is, the more examples you need. Examples are like a pair of glasses that bring fuzzy objects into focus, allowing users to see clearly.

Examples Contain Strategy

One subtle reason why examples give documentation such a boost is because examples contain strategy, and documentation usually lacks strategy (focusing instead on the how-to only). But when you create examples, you sneak strategy in by default, if only a little.

For example, ever notice the timestamping feature in WordPress? It allows you to change the date of posts into the future, so that you can set a post to publish several days or weeks from now.

Sure that feature is clear … but what's not clear is why would I want to set posts to publish in the future.

An example clarifies: Suppose you know that publishing at 11am gives you the most readability for your posts, but at 11am you're at work and blogging isn't allowed, or you live in China so 11am PST is the middle of the night for you. By timestamping your posts at the most optimal hour, you can increase the readership of your content. Now the feature is more clear.

It would be hard to give an example of timestamping that didn't involve some strategic insight. For example, one writer I know writes half a dozen posts on the weekend and then just sets the timestamp of each post to publish throughout the week, while he goes on cruise control. That's strategy infused with help!

Mark Baker writes about the need to include more strategy in documentation. In The Real Docs Need Is Decision Support, he explains,

In tech comm, we don't talk much about decision support. We talk about task support. We frame our jobs as providing the information people need to complete their tasks. Unfortunately, what we often provide by way of task support are simply procedures for operating machines. But, as I have argued before, a task is not a procedure. In many cases, the support people need to complete their tasks is not information on how to operate machines, but information to support their decision making. Its not “how do I push the button,” but “when and why should I push the button and what happens if I do.”

In other words, if help material intends to help people complete tasks, and tasks involve decisions, help needs to include more than the technical how-to steps. It needs to involve a bit of information needed to make a decision about what to do (i.e, business strategy). Examples help facilitate this kind of decision support in help.

Examples in API Documentation

With API documentation, code examples are perhaps the most important part of the whole documentation. You could try to explain how to space and punctuate the code, adding some values in parentheses, others without, and concatenating methods, and such, but the ability to see it in action trumps all.

Phillip Withnall, a programmer, recently wrote a post titled How not to write a specification, noting that not only do you need "precise descriptions of constraints", you also need good examples.

Ben Minson has a more substantial post on the importance of code examples in API Documentation. Ben quotes a study that finds developers use Stack Overflow more than official documentation mainly because Stack Overflow contains many more examples than official documentation. Additionally, many of the examples address edge cases and errors. (See What Does Effective API Documentation Look Like).

API documentation typically gives users a variety of tools without noting all the reasons why you would want to make the calls. Examples let users know how and why the tools might be used in practical scenarios.

For example, one API call might be a create method, and the documentation will no doubt explain how the method is used, the arguments it accepts, the expected response, and so on.

But under what conditions might one actually use the create method? To create what? That's where the example clarifies. The example might explain that you can attach the create method as an event listener to your website login form so that when users log in, a new player gets created (or something).

Hands down, writing API documentation is the biggest trend in Silicon Valley tech comm scene. I'd say that nearly half of the jobs here are for writing API and SDK documentation. If you want to do a good job with API and SDK documentation, you need abundant code examples showing how to use the API or SDK in a variety of scenarios, showing different code techniques and methods. Clearly more attention needs to be given to the use of examples.

Beginning-to-End Examples

Another help topic that has promise for becoming its own topic type is the beginning-to-end scenario. Show the user how someone might use the application in a typical scenario, from beginning to end. Documentation that exists as isolated tasks disconnected from each other doesn't accurately reflect the real scenarios of users, who use tasks in context of each other several at a time.

For example, in Illustrator, you rarely use one tool from the toolbar alone. You use tools in combination with each other. You use the pen tool to draw a basic outline, which you then color, which you then add gradients to, and strokes, etc. But no help topic shows you these multi-process workflows or more rounded uses.

The beginning-to-end example helps bring discrete topics together into one unified workflow.

Examples in Screenshots

Screenshots are another, more subtle way to provide examples in documentation. Giving the user the ability to look and see an example of how to complete the fields on a screen provides a quick, at-a-glance method for helping users know just what to do.

Especially when an interface provides blank boxes and expects specific syntax, such as {"container":"item"} and so on, the example of the syntax is much better than the description of the syntax.

Anecdotal Examples

Another great use of examples is with the stories, or anecdotes. Anecdotal examples (brief illustrative stories) are less common in tech comm but are probably the most interesting kinds of examples you can add to content.

Anecdotal examples not only illustrate how a product might be used, they include an actual actor in a real scenario. They're like little case studies embedded in your documentation.

Good marketing uses anecdotal examples all the time. Tech comm can leverage this content where relevant in the documentation.

For example, suppose you're writing about the gizmo features of your call center software. You know marketing has published a case study with ACME company and the case study discusses their implementation of the gizmo feature. In the help for the gizmo feature, take the opportunity to summarize and link out to the marketing case study.

Bad Examples

You can rarely go wrong by including examples. About the only trouble you'll get in is including bad examples that show incorrect implementations of the product. If your example suggests misuse, it can guide users down the wrong path.

For example, let's say you're writing code samples and you provide an example that has excessive API calls. Users might incorporate the same bad coding examples into their own sites.

Alternatively, consider the damage that a screenshot can do if the screenshot contains sample values that are incorrect or ridiculous. The screenshot may be the only thing the user even looks at when skimming through the help.

Why We Omit Examples

I don't think many will disagree about the usefulness of examples. Examples liven up nearly any kind of writing. Take the examples out of this post and the content becomes dull.

But if we agree that examples are helpful to users, why are examples so frequently absent from help documentation? Several possible reasons explain the lack of examples.

Brevity Teaches Us to Cut Excess/Examples

First, in the spirit of brevity and minimalism, we're taught to strip out all unnecessary words. Here's a brief excerpt from an A List Apart article titled Good Help Is Hard to Find on striving for brevity in help:

People follow the path of least resistance to a goal, and if task instructions take too long to process, they're likely to abandon the quest. Help content should be brief, containing just enough detail to address the problem and get the user back on task.

If you shave and reduce and keep hitting that delete key, you'll end up with a one or two sentence description of a feature, devoid of any context of example to clarify how it's used or what it's used for.

I'm not saying brevity is bad, and certainly an example that accompanies an obvious instruction should be cut, but if we focus on more difficult, technical details in our help material ([as Mark Baker suggests])(http://everypageispageone.com/2012/11/20/tech-comms-obsession-with-novices-has-to-stop/), one might expect an increase in the number of examples to clarify these more difficult concepts.

Task-Based Topics Don't Have a Natural Space for Examples

Another culprit that steals examples from help is the task-based topic. If you follow a heavily task-based model, you may begin with a 1-2 sentence description followed by a series of steps. Where in that task-based topic do the examples fit in? There's no room built specifically to accommodate them.

Since help is supposed to be focused on the doing, the tasks, the examples often get marginalized. Yet it's in the very process of doing that we often need the most assistance. Examples provide users with actions to imitate.

Examples may fit more logically into the conceptual sections of articles (not the task sections), and if so that's fine. But remember to include them somewhere. Task sections can often point to conceptual areas with links to the examples.

Our Familiarity Blinds Us to Complexity

Finally, our own familiarity with applications and concepts often blinds us to the need for example. We may assume that because a feature is clear to us, users need only brief explanations to immediately understand it.

Or we may tell ourselves that in the business context of the user, the user already understands the need and purpose for the feature. The user needs only the steps to complete the task. We say, our users are fully immersed in a world and context where the feature's need is immediately apparent, and the user needs only the steps to execute the task.

That reasoning is kind of flawed, though, because software rarely targets a specific user group with such precision. Usually software has all kinds of features, some created by request for a certain (often high-paying) user base but not for others. To other users, these features may be bewildering.

At my work, we recently added a feature to our software to fulfill a specific request from a customer. I'm sure that other customers will stumble on the screen and scratch their heads wondering what it's about, and why someone would want to include such and such codes in their header.

These reasons probably contribute to the elimination of examples from help. The result is a document so dry and boring that few find any value to it. Devoid of strategy, context, and meaning, the help is little more than an occasional last-minute reference.