---
title: "Examples Are a Primary Way That Complicated Concepts Become Clear"
date: 2013-08-20
description: "$( document ).ready(function() { // Handler for .ready() called. $("
canonical_url: https://idratherbewriting.com/2013/08/20/examples-are-a-primary-way-that-complicated-concepts-become-clear/
---
# Examples Are a Primary Way That Complicated Concepts Become Clear
> The help doesn't provide concrete examples that make the concepts understandable.

[![Pollexamples2](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/pollexamples2.png)](http://poll.pollcode.com/ufx74_result?v#sthash.3bjO11fJ.dpuf)

[(View total votes.)](http://poll.pollcode.com/ufx74_result?v#sthash.3bjO11fJ.dpuf)

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.

![Timestamp](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/timestamp.png)

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](http://everypageispageone.com/2012/11/05/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](http://tecnocode.co.uk/2013/07/30/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](http://beyond-help.net/2013/04/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.