Explained

Explanations that accompany your samples are as important as the samples themselves.⁵ Even the cleverest of code samples need your writing skills to provide your readers with context.

Your documentation should explain any prerequisites to running a code sample, like installing any specific libraries or setting environment variables. Describe any limitations to the code, for example, if the code only runs with certain versions of a programming language.

Introduce code samples with a clear explanation so that your readers know what to expect if they run or encounter this code. Specifically, your explanation shouldn’t be a description of what it does, but why it does it. Really useful code samples explain anything that’s unique to your software, for example, an odd naming convention or particular method.

If the sample immediately follows an instruction or explanatory line, end the line with a colon (Listing 5-3).

If you provide a sample input, follow it with a description or sample of a successful output that matches what your users would see.

Include samples of any common errors that users might experience. Make sure samples match actual outputs.

For more complex code or lengthier samples, consider including inline comments with executable code. If you use comments to break up larger samples, keep comments short and to the point. Use comments to explain the intent behind the code, explaining the “why” that may be missing to someone reading your code for the first time.

If you find yourself writing lengthy explanations, consider whether the code needs to be less complex to make a good sample. If you can, refactor the code into a simpler sample. Otherwise, talk with the engineers for the product, and let them know that a particular use case requires elaborate interaction with the code base and could be a source of confusion.

Concise

Making code samples concise doesn’t just mean making them shorter. It means making sure your samples convey the essential information users need to complete their task, and nothing else. Keep your sample focused on the specific use case you’re trying to highlight, without adding anything unnecessary. It should only show the features you are documenting at that point.

Irrelevant code or overly complicated examples can confuse your reader and make it difficult to see the intention of your code. It also makes it harder for readers to copy and paste your code and modify it for their own purposes.

Clear

You may need to refactor your code in order to make a good sample. In the process of documenting your software, you may find all sorts of shortcuts and scrappy code you wrote in order to ship a change. That may be helpful to you, but can be confusing for a reader.

In addition, follow any existing code style conventions for your language or project. Some large open source projects create their own style conventions, as do most languages. Following existing style guides creates less cognitive overhead for your readers. The result should be clear, readable, and consistent samples so your reader ends up using code that already follows best practices.

Usable (and extensible)

Part of the delight of a well-crafted code sample is the amount of time a reader can save by copying and pasting. However, a reader often needs to replace some data in order to make it applicable for them. It’s important that a reader knows both when to replace sample data and what to replace the data with.

Avoid using foo , bar, acronyms, or gibberish terms that may mean a lot to your development team and not a lot to your reader. Terms like foo and bar may be familiar—even standard—to developers with a traditional background, but developers increasingly enter the field through nontraditional education and experience. It’s better to write looking forward than backward.

Make sure it’s clear where you expect your reader to get any replacement data from. For example, in a sample where readers provide an access token, indicate where readers can find or create the access token.

Trustworthy

Concise, clear, and usable samples ensure consistency, which builds trust with your reader. It only takes one incorrect or broken sample for your reader to lose trust in your documentation and by extension your software. For example, a sample error code that doesn’t match what readers actually encounter makes it much harder for users to diagnose and fix any problems.

Use production-ready code where possible so your readers can use your samples with confidence. Clearly mark any alpha or beta features to let readers know they may be subject to change.

To make sure your samples are trustworthy, test and review your code samples regularly. A later section in this chapter provides advice for testing. Chapter 11 gives more guidance on overall documentation maintenance, including regular code sample reviews.

Choosing a language

Sometimes , it’s easy to get caught up in the question of which language to write your code samples in. If your users work primarily in one programming language, then answering this question is easy: provide samples in your users’ language.

If your users work in multiple languages, then you may find yourself struggling to decide which language(s), and how many, to support in your code samples. Generally speaking, provide samples in a single language that is familiar and most likely to be used by your readers. For example, choose the language of a popular client library supported for your API. For API documentation, consider providing curl samples and allowing your reader to generate samples in a language of their choice.

If you have the time and tooling, you can provide code samples in multiple languages, but be aware that adding multiple language samples adds additional maintenance overhead to your documentation.

Highlighting a range of complexity

Every reader approaches your documentation with a different level of comfort and confidence in using your software. Your documentation should support readers across the spectrum of comfort and familiarity by providing code samples with a range of complexity. With a range of samples, your readers can opt to read and follow whichever layer of complexity is most helpful to them.

For complete newcomers, simple examples to help get started are usually most beneficial. Think of a typical “hello world” tutorial with small, short samples. Hello world exercises are quick to complete, don’t require much additional input from the reader, and provide lots of context to explain what is happening and why.

For readers more comfortable with your software, you may want to follow the newcomer-friendly options with more complex examples. These could be code samples for specific use cases when the reader is already familiar with the core concepts in your software. Limit examples to one use case per page: avoid mixing newcomer and advanced documentation!

Presenting your code

Code samples need good presentation.

Since your code samples are what your readers are looking for, choose formatting and styles that help your code visually pop out of the page. You can use a surrounding box and a different font and background color to make your code samples visually distinct from the rest of your documentation.

The text of your code samples should also look like code. Limit sample lines to 80 characters, and format code samples in a fixed-width font. For example, use backticks in Markdown or the element in HTML.

Most documentation tools have predefined styles to help you format and present well-formed code samples. For example, some documentation platforms let you use tabs to present code samples in different languages.

Testing code samples

Code samples, especially runnable code samples your reader may use in production, must work. There are many packages available to help you test code samples before adding them to your documentation. You can also store the samples themselves in GitHub or another source repository and run tests against them there. Once the samples pass their tests, you can embed them in your documentation.

Sandboxing code

Providing code in a sandbox lets you give your readers the chance to play with sample code safely. Unlike other types of code samples, a sandbox lets your reader interact with the sample before they implement it. Sandboxes help readers build greater trust with your software before using it in production.

Sandboxes take a lot of time and effort to create properly. A sandbox may be worth the investment if your software is particularly risky or sensitive in some way, and you’re sure you have the time and bandwidth to maintain it. Sandboxes are also incredibly helpful if your samples require a lot of customization to make them applicable to your reader.

In the majority of cases, sandboxes are likely excessive, and you may better meet your readers’ needs by investing in good test coverage for your samples or autogenerating them from source.

Autogenerating samples

Autogenerating code samples directly from source can be incredibly helpful. Tightly coupling documentation and code often means easier maintenance and a better experience for both you and your reader.

For example, output code, like API responses or error codes generated with the help of an OpenAPI spec or similar tools, ideally mean that your code samples automatically reflect any changes to your API. However, no matter which tool you use, autogenerated samples need human input and review. Your readers need context to understand the intent behind your code. At minimum, human input often means rewriting code comments to make them reader friendly.