Put the warning beside the exact step it concerns, name the specific risk and the condition that triggers it, and say what to do instead, in two or three sentences. Warnings that are vague, distant or everywhere get ignored. Use them sparingly so each one still carries weight.
Why most warnings fail
Readers skim docs for the command to run. A warning at the top of the page, three screens above the step, is read once, if at all. A warning on every other paragraph trains readers to skip callout boxes entirely. A warning that says "be careful" gives them nothing to act on.
A useful warning has to survive the skim. That means it is close to the step, short, and concrete.
The three part pattern
Each warning answers three questions in order.
- What goes wrong? Name the consequence: "anyone who can reach this port can run code on the host".
- When does it apply? Name the condition: "if the server is reachable from outside your machine".
- What should the reader do? Give the action: "bind to the loopback address, or put authentication in front".
| Weak version | Stronger version |
|---|---|
| Be careful with debug mode. | Debug mode shows an interactive console to anyone who can reach the server. Turn it off before you deploy, and keep it bound to localhost while you test. |
| Do not use this in production. | This sample stores passwords in plain text. Use a password hashing library before real users sign up. |
| Keep your keys safe. | This key can delete data. Store it in an environment variable and never commit it. |
Placement and form
Place the warning directly above or below the command or code block it concerns, never in a distant introduction. If the risk only applies to one option, attach it to that option.
Use the same visual style for every security warning across the site, and reserve it for security. If the same box also holds style tips, readers stop trusting it.
Do not rely on colour alone. Start the box with a plain word such as "Warning" so screen readers and text views carry the signal too.
When a warning is the wrong tool
If the risky path is the default, a warning is a weak fix. Change the sample so the safe path is the default and describe the risky option as an opt in. A warning explains a trade-off. It should not excuse a bad default. For ideas on defaults, see secure defaults design checklist.
Also consider removing the risky step altogether. A tutorial that needs three warnings may be teaching the wrong way to do the job.
A review routine
- List every warning in the docs and mark whether it names the risk, the condition and the action.
- Delete warnings that fail all three and rewrite those that fail one.
- Check each warning sits on the step it protects.
- Count the warnings per page. If a page has more than a couple, ask which are real.
- Revisit them when the product changes, since a warning about a removed behaviour erodes trust.
Safeguard's policy gates and guardrails take the other approach: they enforce a rule in the pipeline, so safety does not depend on readers noticing a callout. Where docs warn, a gate can check. Try the free scan at https://gold.safeguard.sh/scan.
Quick check
How many security warnings should a page have?
Few. If every paragraph has one, readers learn to skip them. Keep them for real risks.
Is a warning enough for a risky default?
No. Make the safe choice the default and document the risky one as an opt in.
Last reviewed: 19 October 2026.
