I think it was Fabrizio Ferri Benedetti who made a list about topics he would like to see writers write about. Or maybe I saw it in a discussion in the Write the Docs Slack. Regardless of that, I think this subject is worth a post.
To be honest, I just wanted to acknowledge this was not my original idea. But, in this day and time, what is an original idea? Let’s continue,
Notes, callouts, and alerts are great for highlighting important info. When used right, they help people understand better and avoid mistakes. But if you overdo it, they can make things messy and confusing. So let’s look at how to use them wisely.
The golden rules of notes and callouts
Most style guides say a few things are key:
- Use them less often. If every paragraph is important, then nothing is.
- Make the label clear. Just saying “Note” doesn’t tell readers why it matters. (I explain this later.)
- Stick to common terms. Words like “Warning” or “Caution” have clear meanings. Use them as intended.
- Keep it short. If you have a long note, consider making it its own section.
- Put related notes together. Don’t spread them out across a page, it can be hard to follow.
Instead of this:
Tip: Before you start, check all required values.
Note: Admin permissions are needed for setup.
Important: Restarting the service too soon might cause a failure.
Try this:
Configuration considerations
Before you start, remember these points:
– Restart warning: Restarting too soon could lead to problems.
– Permissions: You need admin rights.
– Pre-checks: Know all required values first.
This approach keeps things tidy while highlighting the main points.
Choosing the right callout
Different style guides have different types of callouts. Here’s a quick guide that summarizes some of the most common callouts.
Common types of callouts
The following table includes different types of callouts with some examples so you can better understand their purpose.
| Label | Purpose | Example (when to use it) |
|---|---|---|
| Tip | Helpful advice that makes a task easier but isn’t essential. | “Use --verbose for more detailed output.” |
| Note | Extra context that’s useful but not critical. (If it is critical, add it to the main doc.) | “This feature was introduced in version 3.2.” |
| Important | Key details that, if missed, could lead to extra work. | “If you are using a different installation, configure the correct environment variables accordingly.” |
| Warning | Alerts about data loss or security risks. | “Deleting this file is permanent.” |
| Caution | Alerts about unintended side effects. | “Enabling this setting may impact performance.” |
| Best practice | A recommended approach that improves outcomes. | “Use environment variables instead of hardcoded credentials.” |
| Limitation | A known issue or restriction. | “This feature is not available on macOS.” |
| Security note | Security-specific warnings. | “Never expose your API keys in client-side code.” |
While I personally think Limitation and Security note may be overkill (limitations could be explained on the overview and security notes can be a Caution or Warning), it’s important to acknowledge they exist.
Other style guides include a Prerequisite callout… I’d rather have prerequisites as their own section, but I understand that using certain documentation tools or structures makes this hard or just impossible.
You can simplify your options as much as possible and that would probably be for the best.
Google’s developer documentation style guide (internally) also includes Consideration (for trade-offs) and Experimental (for beta or preview features), helping to manage user expectations and guide decision-making.
When not to use a callout
Sometimes it’s better not to use callouts. Here’s when to skip them:
Avoid callouts if…
- The info is already in the main instructions. Instead of saying:
Note: Install dependencies before running the command.
Just write:
- Install dependencies.
- Run the command.
- It belongs in the intro or requirements. Rather than saying,
Prerequisite: This feature only exists in the Enterprise edition.
Move it to the Requirements section.
- The note is too long or has too many points. Instead of:
Note: Windows users need WSL, Mac users need Homebrew, Linux users should check their package manager.
Break it down into a section called “OS setup”
- The note states the obvious. For example,
Note: Click “Save” to save your changes.
Not needed.
Use callouts if…
- A step has an optional shortcut or efficiency hint. That’s a tip.
- You have an important point that doesn’t fit neatly into the flow. That’s a note.
- Key details could lead to extra work if missed. That’s an important callout.
- You need to warn about something that can’t be undone. Like data loss or a security issue—that’s a warning.
- A setting or action might have unintended consequences. That’s a caution callout.
- A procedure that should be followed to avoid future issues. That’s a best practice.
- A known limitation could affect user expectations. That’s a limitation. Use it only if you know that users expect something they won’t get.
- Security concerns need to be highlighted. That’s a security note.
- A feature is in beta or subject to change. That’s an experimental callout.
- A decision has trade-offs. That’s a consideration.
(This subsection is inspired on a Write the Docs Newsletter)
More resources on callouts and style guides
Want to learn more? Check these out:
- Google developer documentation style guide | Notes
- GitHub style guide and content model | Alert types
- Write the Docs: Using callouts/admonitions in tech docs
These guides and newsletters can help you use callouts well.
Final thoughts
Callouts are like spices in cooking. A little can make things better, but too much can overwhelm (unless you are Mexican, like I am, but that’s not the point). When used wisely, they help readers follow along without getting distracted.
How do you handle callouts in your docs? Have tips for keeping them helpful and not obtrusive? Share in the comments!
Leave a Reply