Text formatting
Format the text of a page: when bold and italics apply, how internal links and asset paths are written, and when a list is numbered.
Use bold for UI labels and product names
Bold marks a label the reader must find on screen, and it marks a product name. Everything else stays plain, because bold for emphasis competes with those two jobs. A paragraph with three bold phrases has none.
- Incorrect:
You **must** purge the cache **before** you deploy the **new version**. - Correct:
Purge the cache before you deploy the new version.
Bold does its job when it points at the interface: Select **Save** to apply the change. The reader knows which word to look for.
Use italics for UI values and defined terms
Italics mark a value or option the reader picks in the interface: Set the permission to _Read Only_. The label is bold; the value is italic.
Italics also mark a term at the moment the page defines it: A *cache key* identifies one object in the cache. After the definition, the term appears in plain text. Italics anywhere else dilute both signals, so the documentation uses them rarely.
Use monospace for code and typed values
Monospace marks code and anything the reader types: commands, paths, field names, flags, headers, status codes, and filenames.
Tool names take monospace, never bold: azion, npm, curl. Bold names a product; monospace names the command the reader runs.
The three styles divide the work: bold for the label, italics for the value, monospace for the typed text.
Never underline, and never bold a link
Underlining belongs to links alone. An underlined word that is not a link reads as a broken link, and the reader clicks it.
Do not bold the text inside a link either. The link already carries its own styling, and bold on top of it competes with the bold that marks UI labels.
- Incorrect:
Refer to [**Cache settings**](/en/documentation/platform/applications/cache/cache-settings/). - Correct:
Refer to [Cache settings](/en/documentation/platform/applications/cache/cache-settings/).
Format internal links
An internal link is absolute, starts with the language prefix, and ends with a trailing slash.
- Incorrect:
[Applications](../build/applications) - Correct:
[Applications](/en/documentation/platform/applications/)
Asset paths follow a different rule. One image serves both language versions of a page, so its path is root-absolute with no language prefix.
- Correct:
/assets/docs/images/uploads/diagram.png
Write link text that names the destination
The reader decides from the link text alone whether to follow the link. “Click here” names the action instead of the destination, and a bare URL buries the destination in syntax. Both force the reader to read around the link.
- Incorrect:
To learn about sentence rules, [click here](/en/documentation/style-guide/writing/sentence-structure/). - Correct:
The sentence caps are defined in [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/).
Two standard forms cover almost every link sentence:
For more information, refer to [Page Title](/en/documentation/.../).To <do something>, refer to [Section Title](/en/documentation/.../).
Do not write Learn more about..., To read more..., click here, this page, or a bare URL in prose. Link text names the destination.
A closing-section link carries its reason. In a ## Next steps card or a ## Related resources row, the title is the destination and the copy is one sentence on what the reader gets there.
Link text is unique on the page. Two links with the same text must go to the same place, because a reader who sees the same words expects the same destination.
Links inside a paragraph point at documentation pages. External links gather at the end of the page or the section, so the reading flow never leaves the docs mid-task.
Link the first mention of another documented element
When the prose names a product, a platform resource, or a feature that has its own page, the first mention on the page links to that page: Configure a [firewall](/en/documentation/platform/firewall/) to protect the application. Later mentions stay plain, or bold where the product-name rule asks for it.
The link replaces the bold at that first mention, because the text inside a link is never bold. A reader who meets an unfamiliar name always has its page one click away.
Use asides for what the text cannot hold
An aside carries information that is useful but does not fit the flow. The four variants divide the job:
| Variant | Carries |
|---|---|
:::note | Useful information that does not fit the flow |
:::tip | A shortcut or a recommendation |
:::caution | An action with consequences the reader must weigh |
:::danger | An action that breaks something or exposes data |
Three limits keep asides readable. Use at most one aside of a kind per section. Keep an aside to three short paragraphs. Never put a heading inside an aside.
An aside never carries the primary answer. The reader who skips every aside must still complete the task from the flow alone.
Number a list only for sequence
A numbered list promises order: the reader takes step 2 after step 1. When order does not matter, the list takes bullets. When only one item exists, write a sentence, because a list of one is a sentence with a bullet in front.
The sentence rules for steps are in Sentence structure.
Keep list items parallel
Items in one list share one grammar: all start with a verb, or all start with a noun. Mixed grammar forces the reader to re-parse each item, and the list becomes slower to scan than a paragraph.
Incorrect:
Correct:
Use tables for enumerable content
Fields, limits, flags, defaults, and status codes belong in tables. Reference readers scan a table; they do not read it. Two rules protect that mode of reading.
Phrase a column consistently. A column that reads Enables the cache, then this option turns on logs, then compression on describes one kind of fact in three shapes. Each new shape forces actual reading. Write Enables the cache, Enables logs, Enables compression.
State the unit and the default for every value. A limit without a unit is not a fact: a cell with 100 leaves the reader to guess between megabytes, seconds, and requests. Write 100 MB, and state the default where one exists.
Introduce every table with a sentence that says what it shows. A table that arrives without context is data the reader must reverse-engineer.
Never put a table in the middle of a numbered procedure. The table interrupts the sequence; place it before the steps or link it.