Code
Run every command before it ships, keep placeholders that cannot be mistaken for real values, and keep credentials out of code blocks.
Run every command before you publish it
An untested code block is a guess that looks authoritative. Prose signals uncertainty with words; a code block signals nothing, so the reader executes it with full trust. On the page, a guessed command is identical to a tested one. The difference appears when the command fails, on the reader’s machine.
Run every command and every snippet before the page ships. When you cannot run one, do not publish it. A page that states less, and is right about all of it, beats a page that guesses.
Compose, do not invent
A code block mixes two kinds of content: the facts it carries and the syntax that expresses them. Tool syntax needed to express a sourced fact — curl flags, a Content-Type header carrying a given JSON body, shell quoting — is composition, not invention. A new product value, field, endpoint, or default is invention.
For the rule that every specific traces to a source, refer to Word choice.
Make placeholders obvious and consistent
A placeholder has one job: the reader must see at a glance that the value is theirs to replace. Two formats do that job: brackets with capitals, [TOKEN VALUE], and angle brackets with lowercase words, <your-bucket-name>. Use one format for every placeholder on a page; three conventions on one page teach the reader none.
Each kind of value has a reserved form:
| Kind of value | Form |
|---|---|
| Secret or token | [TOKEN VALUE] |
| Reader-supplied name or value | <your-bucket-name>, <your-azion-domain> |
| Example domain | example.com, example.org |
| Example IP range | 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 |
The IP ranges are reserved for documentation and route nowhere.
- Incorrect:
--token abc123 - Correct:
--token [TOKEN VALUE]
abc123 reads as a value that might work, and a reader in a hurry pastes it unchanged. [TOKEN VALUE] cannot pass for a real value. The worst placeholder is a realistic fake, because it hides that there is anything to replace.
Introduce every code block
One sentence before the block states what the code does. A bare code block is a snippet the reader must reverse-engineer before deciding whether to run it.
Tag the language, and name a file only when there is one
The language tag on a fence drives the highlighting and names the language in the bar above any block of two or more lines: bash reads Shell, json reads JSON. Give every fence a tag, and text to output that has no language. A one-line block shows no line numbers, and no bar unless it has a title.
Add title="..." only when the block is a file the reader saves, such as title="azion.config.js". The file name takes the language’s place in the bar. The props are in Components.
Leave the prompt out of copyable input
No $ or > before a command. The reader pastes the line, prompt included, and the command fails. A prompt belongs only in output shown in a fence, where it reproduces a real session.
Write comments as prose
A comment inside a snippet follows the page’s language and the sentence rules, and says why, not what. A comment that restates the line under it adds nothing.
Keep credentials out of code blocks
No real credential appears in documentation: not a live one, not an expired one, not a revoked one. On the page, an expired credential is indistinguishable from a live one, so the ban covers them all equally. A fabricated value with a realistic shape is banned for the same reason: no reader, and no scanner, can tell it from a leak. Write the placeholder instead: [TOKEN VALUE].
This section shows no incorrect example. A realistic fake credential in a style guide is still a realistic fake credential in public documentation.