Advent of Technical Writing: Callout Boxes

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.

When you are writing documentation, there may be some important information that you want to highlight to readers. You can do this in a few ways, such as by emboldening text or by adding a callout box. Callout boxes are visually distinct regions on a page that “call out” a particular piece of information.

Callout boxes can be styled in any way, but typically use the following hierarchy and colour scheme:

• Critical: A red box. Used for critical information. Use sparingly.
• Warning: An orange box. Used to highlight important information.
• Note: A piece of information you want to call out, but is not a warning.
• Tip: A handy piece of information that you want to highlight.

Let me talk through a few examples of these. Note: I don’t have an example of critical boxes to hand, but I do recall seeing a few so I wanted to add it above.

Warning Callouts

You may use a warning callout to inform a reader that:

1. The API documented on a page is unstable. If possible, you should give a timeline on when the API will be final, and where the reader can go to check for updates.
2. An API has been officially deprecated. Such a callout should link to the relevant documentation for the new API.
3. A page is incomplete.
4. A page is under active maintenance and may change.

For example, I used a callout in a guide in Inference, an open source computer vision inference server, to say that the model documented by the guide was not available. This box was added because we wanted to document that the model was being worked on so that users knew to check back for more information. Here is the callout:

Note Callouts

Note callouts are effective at highlighting information that you want to be highlighted but is not a tip, a warning, or a critical message.

You may use notes to:

• Highlight information about how different versions impact an API response.
• Call out that a task may take a while to complete.
• Inform the reader that they need to have an API key to follow a tutorial, with guidance on how to find one.

For example, I used a note to share guidance on the tasks at which a particular vision model performs well in a piece of documentation. While the information is close to a Tip, which I will document below, my guidance was not about direct usage. Rather, the information about what the model does well and does not do well could be used by a reader to evaluate if the solution in the guide is going to be useful to them.

Tip Callouts

Tip callouts are used to highlight additional information that helps a reader effectively use a piece of software.

You may use a tip to inform a reader that:

1. Reviewing a prior guide will give them the context they need to better understand the content of the page they are viewing.
2. A particular optimisation will help them save time.
3. A keyboard shortcut is available to perform a task.

For example, I have used tips to inform readers that a previous guide gives valuable context that will help them make the most of the page that they are viewing. Here is an example:

That’s it for today’s technical writing tip! See you tomorrow!