Examples in tech articles

Technical documentation is often dense with new information. Your reader is expected to take in a lot of data, process it so that it's meaningful in theory, and then put that collated data into practice. There's usually a lot of mental connections for a reader to make between their own technical environment and use case, and what your documentation is describing. Examples, such as code samples or commands or flowcharts or blueprints, can help your reader envision the results of a process without having to take the time to implement anything while they're still trying to parse what they're reading. However, an example has just as much an opportunity to be confusing as anything else, and in some cases documentation relies so heavily on examples that there's hardly any documentation in between. Here are some things to consider when planning out what and how you demonstrate concepts in technical documentation.

Examples to provide confirmation

Some examples are provided in documentation just to affirm that the reader understands what you're describing in documentation. It can be as simple as displaying a code function or command followed by sensible output, or a screenshot showing a message confirming success. These kinds of examples serve as waypoints along the reader's journey, whether it's practical or academic, through the technology you're writing about.

It's usually safer to show success rather than failure, because there are more ways for any technology to fail than for it to succeed. You can't anticipate all fail states, but you can certainly display a valid success condition. This broadcasts to the reader what kind of output or result they must receive before continuing in whatever process your documentation is describing.

Suppose you've written this statement:

The echo command prints its input as output.

To many readers, that's a clear and sufficient description of the echo command. But if you've never seen the echo command in action, you may still have questions about what to expect. Is the output of echo visible to the user? Does the output include a newline character? Does the echo command require its input to be wrapped in quotes?

An short example scenario implicitly answers many questions:

$ echo hello world
hello world
$ echo -n hello world
helloworld$

This sample example isn't sufficient by itself, however. It leaves a lot of interpretation up to the reader, which brings me examples used as a way to provide instruction.

Examples to provide instruction

Sometimes, you want to demonstrate how to achieve a specific result. This can be helpful for the reader, but it's a potentially dangerous trap for you as the author. It's easy to rely too much on an example under the assumption that what you're trying to demonstrate is self evident. An example rarely speaks entirely for itself, and trusting that a reader can reverse engineer what your example code or screenshot is meant to demonstrate undermines the very purpose of documentation.

When you include an example, whether it's code or a screenshot, make sure you're also explaining why the example results in success or failure. If you can't explain everything in the example without writing a whole dissertation, then tell the reader what assumptions you're making about their level of knowledge. In the event that a reader doesn't understand something vital to the process, they can choose to do further research as a separate exercise.

Continuing with my previous sample, suppose you've written this description of the echo command:

The echo command prints its input as output.

Instead of demonstrating all possible uses of echo all at once, you first provide this example interaction:

$ echo hello world
hello world
$

Then you write more detail about the command's options:

Use the -n option to omit a trailing newline character from the output.

And then you provide an example that demonstrates how the -n option is used and how its usage produces a different result from the previous interaction:

$ echo -n hello world
helloworld$

Examples to provide context

My previous sample examples imply assumptions about the reader's understanding of an operating system shell, or command-line interface. All documentation must make some assumptions about its reader, and usually readers are able to detect whether they're ready for documentation based on their familiarity with the subject matter of the first few pages. However, documentation at any level exists to educate. The less you rely on your reader's familiarity with a subject, the more you liberate your reader from mental cycles external to your documentation. Without belaboring the foundational knowledge of your topic, providing context is almost always appreciated by any reader trying to focus on learning something new.

For example, suppose you're writing documentation for an application using the Lua programming language for extension support. Your audience is expected to have some understanding of programming, but not to have used Lua before. You're describing the output of the fictional sn_run library:

The sn_run library loads and runs an .sn file. Using the thread function, it can use any number of CPU cores.

You provide this example code:

sn_run(myfile).thread(6)

This demonstrates to the reader exactly how to use the library, and how to use the additional function. It doesn't provide the user a programmatic way of determining how many CPU cores to use, it doesn't provide the scaffolding required to create or register a valid extension for the application. It only demonstrates the process described.

In some cases, it would be appropriate to reinforce more than just how to use a specific library. If you're still introducing the reader to the basic concept of writing an extension with Lua, then you might provide a full example that they could load into the application and run. Context is meaningful, but it's most useful when it's relevant.

Examples

As with writing, a good example is often one that focuses on the fewest points as possible. Just because you can demonstrate many principles in a simple example doesn't mean that's useful to your reader. Focus on what you're trying to communicate to your reader both in your descriptive text and through your examples. Design your examples so that they support your text, and write your text to support your examples.