Advent of Technical Writing: Code Snippets

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.

Code snippets are an essential part of technical documentation that involves commands and code. For example, one may use code snippets in a tutorial that shows how to use a product API. While code snippets may seem like the easy part of technical writing -- I hear some readers calling out "I already have the code, so I can include it in my post!" -- properly structuring code snippets requires thought and diligence.

Dependencies

First, make sure that you tell the reader exactly what dependencies they need to use code snippets in your guide, and how to install them. This will significantly reduce friction.

Minimum viable code snippets

Second, I recommend striving toward using "minimum viable code snippets." This is the minimum amount of code I know someone will need to accomplish a particular task.

Consider my guide that explains how to deploy vision models offline. Before I wrote this guide, I knew that I wanted to teach someone how to deploy vision models offline. I knew this would involve code snippets. I spent some time thinking about what to write, and decided that my code snippets would fall under two themes:

1. Deploying a model offline to run on images, and;
2. Deploying a model offline to run on video.

Then, I wrote code (or copied code from the relevant product documentation I wrote) that would allow a reader to accomplish both tasks. When I wrote code, I strived to keep the lines of code to a minimum. I wanted a reader to be able to run a model on an image in one section, for example. I provided that code, and some additional code that would let a reader see the results from their vision model on an image. Visualiizing results from a model is separate from deployment, but I considered it relevant because seeing results in computer vision helps a reader build conviction that a solution is working.

Here is an example of a code snippet from my guide:

```python import cv2 import supervision as sv from inference_sdk import InferenceConfiguration, InferenceHTTPClient

image = "containers.jpeg" MODEL_ID = "logistics-sz9jr/2"

config = InferenceConfiguration(confidence_threshold=0.5, iou_threshold=0.5)

client = InferenceHTTPClient( api_url="http://localhost:9001", api_key="API_KEY", ) client.configure(config) client.select_model(MODEL_ID)

class_ids = {}

predictions = client.infer(image)

print(predictions) ```

This is the minimum amount of code someone needs to run a model. I then explain how a reader can use the code, and what values need substituted (see the "Substitutions" section later in this guide for more information). In a separate section, I then elaborated on how to plot code, with refernce to another minimum viable code snippet. I used two snippets, each with their own description, to:

1. Avoid having a very long code snippet, and;
2. Ensure that the main task (running inference on an image) was clearly distinct from an auxilery but useful task (visualizing predictions).

I was judicious in what code I wrote, and didn't write. I could have written more code to show more features of deploying a model offline, but I decided to stick with only what a reader needed to accomplish a task and verify that the code they wrote was working.

In total, I wrote 40 lines of code that show show to deploy a model offline. I could have written 100 with features like counting predictions for each class, adding exceptions to account for a range of edge cases. But this would have made the tutorial more complicated.

A reader should be able to comprehend every line of code you write that you say will solve a problem. The more code, the more a reader has to understand, and the more work a reader needs to do to figure out how to integrate your code into their application.

In short, keep it simple.

Explanations

My final tip is to explain, in text, what a code snippet does. Never assume the reader will understand what your code does without explanation. You may understand the code, but you wrote it. In technical writing, your goal is never to copy-paste code with a few words that explains what problem it solves. Your goal is to help someone learn new knowledge and/or solve a problem. Achieving this goal requires detailed and articlualte explanation on the part of the writer.

Your explanation might be a sentence that summarises the code or may be longer, depending on the audience for whom you are writing and what knowledge you can assume.

Readers can always skim over your writing if they only want code, but a significant portion of your readers will benefit from text descriptions of the code you include in a guide..

Here is an example explanation of a code snippet that I wrote in my offline vision model deployment guide:

When you run the script for the first time, the weights for the model you are using will be downloaded for use on your machine. These weights are cached for future use. Then, the image will be sent to your Docker container. Your selected model will run on the image. A JSON response will be returned with predictions from your model.

You should take extra care to explain details that may cause confusion. For example, you may note how long a code snippet could take to run if the code will take a while to run. You may point out explicit differences between two code snippets in your article if they are similar and have subtle but crucial differences.

Substitutions

Many code snippets cannot be copied verbatim from documentation. For example, you may need to change file names, URL names, or other information in a snippet to use it. You may need to add your own API key. Make sure you explain, in text, exactly what values need substituted and, where appropriate, where to find those values.

Here is an example of how I explained the substitutions required in the code snippet I referenced earlier:

Above, replace:

1. The image URL with the name of the image on which you want to run inference.
2. ROBOFLOW_API_KEY with your Roboflow API key. Learn how to retrieve your Roboflow API key.
3. MODEL_ID with your Roboflow model ID. Learn how to retrieve your model ID.

I stated exactly what needs to be substituted and where to find the relevant values. You should do this in your technical writing, too.

Sharing feedback

Through writing code snippets, I sometimes find myself thinking "there should be an easier way." This is an interesting side effect of technical writing. When you write, you should strive toward making the reader's experience as pleasant as possible.

If you are running into friction with code you are writing for a guide -- for example, code that uses an SDK or a particular package -- that may be a sign that there is feedback you could relay to an engineering team. If you think some code is so general that it could be abstracted into an SDK that your organization maintains, you could make that recommendation. If you find a bug in code, you cam share that with the team.

That's it for today's technical writing tip! Join me tomorrow for another tip!

• Minimum viable code snippets
• Explain exactly what is going on
• Link to useful reading (how to find values for parameters)
• Can you abstract code upstream in a helper function / the function itself