Are you using examples correctly in your technical writing?

Examples in technical writing are a vital part of demonstrating the lesson you're trying to teach. However, some technical writers rely on examples too much, failing to provide context to a principle the author believes to be self-explanatory. Other technical writers fail to include examples at all, presumably believing that their documentation is so clear that they'll inspire the reader to create personalized examples.

To ensure that you're neither over-using or under-using examples, it can be useful to consider what role examples serve in your writing. Here are 5 things about examples you should consider when writing documentation.

1. Does your example have context?

Examples don't speak for themselves. It doesn't matter how brief or simple an example is, it's still a mystery to someone who's unfamiliar with the system you're describing. Worse still, if you rely on the reader to interpret your example on their own, what you intend the example to demonstrate may be misconstrued or missed entirely. Here's an example:

dir Documents

If you look at that example and think it's self-explanatory, then you're probably familiar with the command-line of some operating system. But even if that doesn't quite mystify you, you don't know which operating system it's referring to (although you may think you do). If you're not familiar with the command, then you don't know what the example command does, or possibly even how to try it for yourself.

The dir command is innocuous, but some commands can be destructive when used improperly. Without context, something like dd if=/dev/zer0 of=/dev/sdx could be catastrophic (but not in this case, because I've included some invalid usage to "sabotage" a careless copy and paste).

An example without proper context may as well not be there at all. Tell your reader what an example demonstrates, explain why it's significant, and then let them imagine they're trying it themselves by including an example of what would happen, were they to implement what they've just been taught.

2. Does your context have an example?

It doesn't matter how well you describe a process. If you don't also demonstrate it with an example or screenshot, then you're inviting your reader to forget it once they turn the page.

That might be an acceptable risk for you, depending on what the process is. If you're alerting the reader of something that's unlikely to happen, then including an example might suggest disproportionate significance. Technical documentation is a reference document, after all, so it's fair to assume that a reader expects to refer back to it for edge cases.

However, for a topic you consider essential, it's likely that an example can help emphasize the point.

Appropriately, here's an example.

A conditional statement in Python can be reversed using the not keyword.

This statement makes a lot of sense to Python programmers. Someone familiar with Python has already envisioned a line of example code, and probably has already constructed an alternative way of achieving the same result.

For a reader new to Python, however, the English words probably make sense, but the result is difficult to picture. Let's write it again and include some sample code as an example:

A conditional statement in Python can be reversed using the not keyword.

>>> VARIABLE = True
>>> if VARIABLE is True:
>>>     print("Variable is set to True")

Variable is set to True

>>> VARIABLE = "Blah"
>>> if VARIABLE is not True:
>>>     print("Variable is NOT set to True")

Variable is NOT set to True

That's much clearer with an example.

3. Find a minimum viable example

The more you include in an example, the more you have to explain, and the more opportunity there is for your reader to miss the point. Whether it's a series of screenshots or lines of code, it's probably not a bad idea to look at what you've included in your first draft and then find a way to cut it in half.

Think critically about what you're demonstrating to your reader. If you're including screenshots to show the location of a menu, then you may not need to include a new picture for each and every sub-menu between the top-level menu and the final selection. Once you've established that the reader knows how to take the first step, you can probably trust that the reader can continue to use the user interface to reach the end result. Provide a picture of the first and last steps, and just use text descriptions for the middle parts.

With code samples, don't sacrifice clarity in an attempt to provide usable code. It's nice when a reader can copy and paste sample code into a development environment and run it, even if it's just to see rudimentary output. However, with advanced topics it's not always a realistic goal. With some programming frameworks, even just a “hello world” application can be upwards of 30 lines after all the include statements and required scaffolding.

Sometimes, it's best to just provide a snippet of code as if it had been extracted from a larger code base. Depending on what resources are available to you, it may even be possible to provide that code base as a separate download for readers who do feel the need to see the big picture.

4. Explain the important parts

When an example requires complexity to make sense, it's often best to explain only the important parts.

In a desktop application, there may be some setup steps so that conditions are right for a meaningful example. It's fine to tell the reader to accept the setup steps as requirements for your demonstration, and then to explain just the part you want them to retain.

In code, there may be 10 or 20 lines of boilerplate content that exists only to communicate with the underlying framework. It has nothing to do with what you're trying to demonstrate. Don't try to explain why each library needs to be included, or what each function is doing when they're exclusively serving as the foundation for a specific lesson. Mention the code as necessary setup for the program, and then you can focus on the lines that actually make your point.

5. Reinforce lessons

In real life, there's the principle “lead by example.” It means that when you yourself do a thing consistently, the people around you, usually without even realizing it, tend to learn to do the same thing. It's human nature. We humans can pick up on a pattern, and then think ourselves clever when we're able to mimic that pattern. The same principle applies to technical writing.

You can weave important principles throughout your technical writing simply by putting into practice the things you're trying to train others to do. For example, when I wrote about potentially destructive commands earlier in this article, I used the command dd if=/dev/zer0 of=/dev/sdx to demonstrate something dangerous. However, /dev/sdx is an extremely unlikely device name on a system (like Linux) that starts its devices at /dev/sda. It's possible for a reader to have 24 hard drives connected to a computer, but unlikely.

I also spelled zer0 with a zero character instead of an o because /dev/zer0 is not a valid device, so that the command would fail no matter what, and then communicated that I'd intentionally sabotaged the example command. Safeguarding my readers from catastrophic data loss is important to me, and so when I'm citing dangerous commands I ensure that they can't be accidentally misused. I'm trying to lead by example.

You can do the same thing, within a documentation project and across all the documentation you write.

Repeating concepts across examples helps reinforce them. If you've taught your reader to use True and False in a programming article instead of 1 and 0, then use True and False in your examples, instead of seemingly meaningless values. Similarly, if you've taught your reader to capitalize class names, then do that in all of your examples.

At every opportunity, quietly reinforce a principle from a previous or upcoming lesson.

Examples

It's often said that to teach someone a thing in a classroom, you tell them the thing, then show them the thing, and then to have them do the thing themselves. This services all the most important ways humans learn: auditory, visual, and kinesthetic. It stimulates different centers of the brain, builds muscle memory, and ensures a complete understanding of the principle being taught.

Technical writing for technology, software, and even gaming can't rely on all these avenues of education, though. When you write instructions, you can include pictures to illustrate points, or you can encourage the reader to launch software to try something specific, but it's up to the reader to follow through.

Using examples in your technical writing is an important way to reinforce what you're trying to communicate, and using examples intelligently ensures that readers benefit from them.