Technical writing isn't only long manuals. Most of it is small. A one line definition in a glossary. A warning box above a dangerous command. A description beside a config option. A comment above a tricky loop. These bits get read at the exact moment someone is about to make a mistake, so the wording matters more than its length suggests.

This post collects annotated technical writing examples from the small places in docs and code. Each one shows a weak version, a stronger version and the reason the stronger one works. I've left out READMEs, error messages and endpoint reference pages, since those have their own guides.

1. A definition

Weak.

A tenant is a logical isolation boundary within the multi-tenant architecture.

Strong.

A tenant is one customer's space in the app. Each tenant has its own users, data and settings, and nothing in one tenant is visible from another.

The weak version defines the word with harder words. The strong one says what it is, what it contains and the rule that matters.…