Advent of Technical Writing: Effective Examples

This is a ✨ bonus ✨ post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

Effective examples make technical writing more intuitive.

Earlier in this series, I spoke about the importance of referencing consistent examples in your work. I mentioned that it is acceptable to mention a few different use cases for a product or piece of software, provided those use cases are isolated in a particular section of your work (i.e. the introduction). You should focus in on one example when showing how to use the product, software, or code.

Examples serve as a means by which you can illustrate not only what your software does, but how it works. This can be wrapped in a narrative that helps build a consistent flow across your writing, easing readability.

What makes a good example in technical writing?

How do you choose what example to use in technical writing? That is a good question.

Good examples are:

1. Relevant to the capabilities of your software;
2. Well defined;
3. Intuitive, requiring little background knowledge about any topic in which the reader is unlikely to be familiar, and;
4. Relevant to your target customer (in the case of marketing-driven technical content).

Blog posts and tutorials should have a single, clear example that is used throughout.

Documentation that serves as the canonical reference for how to use a user interface should be example-agnostic, where possible. For example, consider the document titled “Create a Project” in the Roboflow documentation. Here, no example is needed beyond showing the product action. Text like “For example, you could create a project called ‘Cats’ that is used to identify cat breeds” would be superfluous and introduce more words than are necessary for the reader to accomplish the goal.

When I am working with team members who are writing blog posts, I am always available to talk through examples to help them find ones that meet the criteria above. My manager does the same for me.

How I used examples in a blog post

Let’s walk through an example blog post that practices the above advice.

Consider a guide, Distill Large Vision Models into Smaller, Efficient Models with Autodistill. This guide was an announcement for an open source project that featured a detailed guide on how to use the software. This blog post is consistently used as a canonical blog post on using Autodistill, the topic of the article.

Autodistill lets you use large computer vision systems that know a lot about the world to create smaller systems that can accurately identify particular objects. For example, you can use a large model that can identify 20,000 things to train a smaller model that identifies one thing (i.e. a milk bottle). The smaller model will run much faster and can be tuned to be more accurate than the larger model. Autodistill auto-labels images which are then used to create the smaller model.

In this guide, we opted to use the example of milk bottle and bottle cap identification. We showed how to create a computer vision system that identifies milk bottles and bottle caps on a manufacturing line. Such a system could be used in a bottling facility to count bottles at a given point on a manufacturing line, identify bottles that do not have a cap, and more.

Let’s view this example through the four points that I said made a good example earlier:

1. Relevant to software capabiltiies: The example effectively shows the capabilities of the software.
2. Well defined: The example is clearly stated in the article.
3. Intuitive: Although the example is about milk bottles, you don’t need to know anything about bottling facilities to follow the guide. Rather, bottles is used to illustrate the capabilities of the product, which is to auto-label images to make smaller, accurate computer vision models.
4. Relevant to the customer: This example is relevant to our expected audience, which is someone, ideally an engineer at an industrial company, who wants to reduce the amount of labeling time required to solve a problem.

When I write a new tutorial, I always think “what example would illustrate this product well, be interesting to our target audience, and is something that I can make in a reasonable period of time.” That last point is important. Sometimes, I need to compromise when coming up with examples. If an example will take too long to create given the time available, consider if there are other compelling examples that would take less time to create.

Document limitations

When you are documenting software, make sure that you document limitations. Autodistill cannot auto-label any arbitrary image, for example. With that said, a reader could assume that this is the case, since we are introducing a concept that was previously used primarily in academia, and with which a reader in our intended audience may have limited to no knowledge.

Thus, we added balance, noting limitations in a “Best Practices” section. Here is what we wrote:

With that said, there are limitations to the base models supported at the time of writing. First, base models may not be able to identify every class that you want to identify. For more obscure or nuanced objects, base models may not yet be able to identify the objects you need to annotate (or may take extensive experimentation to find the ideal prompts).

If you are documenting APIs, limitations that you may note include:

1. Rate limits.
2. Properties that are not available in the endpoint documented but can be retrieved from another endpoint.
3. Whether an API is available in different SDKs (i.e. if an API is only available via HTTP, but not in your Python or iOS SDKs).
4. An API is about to be deprecated.

Where relevant, link to relevant resources about limitations.

Example bounds

You will also need to decide on bounds for examples. For example, I am documenting a Python library called mf2py with library contributors. This library lets you parse a HTML document to retrieve microformats data in a specific structure.

We decided to create a hypothetical HTML document with an author called “James” that was about Taylor Swift for a test to include in the README. This example was derived from a blog post I wrote, but was trimmed down significantly.

We didn’t think it was appropriate to use the exact post on my blog and reference it by URL, since the page could be moved one day and the URL breaking would make for a subpar experience. The page being down would be confusing if the post was broken and the reader used the post URL in the parse-by-URL example later in the documentation. The output would not be as expected. In addition, the post I had on my blog was too long, which would result in an accurate but overly verbose output. So we trimmed it down.

After this discussion, we started to talk about the role of examples, and agreed to discuss guidelines that err toward more hypothetical examples, even if they are derived from content from the authors. (NB: This discussion is ongoing.)

Join me tomorrow for another edition of the Advent of Technical Writing series!