Formatting

Use consistent formatting to improve clarity, scannability, and accessibility across all documentation.

Apply the following rules consistently across all documentation:

• Use bold for GUI text.
• Use inline code for IP addresses, domains, commands, package names, filenames, paths, options, and flags.
• Use relrefs for internal links.
• Use notices sparingly, and only to call out important notes, warnings, or constraints.
• Use includes to reuse shared or repeated content.

Italics

Use italics sparingly to add clarity, not emphasis. Italics should help readers distinguish concepts, terms, or references without introducing unnecessary styling.

• Capitalize italicized words only when grammar requires it.
• Keep italicized terms lowercase mid-sentence unless they are proper nouns.
• Avoid long italicized phrases.
• Do not italicize entire sentences.
• If a term appears repeatedly, italicize it only on first introduction unless clarity requires otherwise.

Use italics for:

• Conceptual terms when they are first introduced.
• Foreign or non-English words not integrated into English.
• Book titles, publication names, companies, or formal documents when needed.

Do not use italics for:

• Commands, filenames, code, options, or flags.
• UI buttons, links, or field labels.
• Model names, product names, or proper nouns.
• Emphasis or tone (rewrite the sentence instead).

Bold

Use bold formatting for UI elements, including:

• Buttons
• Menu items
• Field labels
• Section names

Avoid using bold for emphasis in narrative text.

Lists, Tables, and Structured Content

Use lists and tables to organize information clearly and consistently. Choose the structure based on whether the content requires sequence, hierarchy, or grouping.

Ordered Lists

Use ordered lists for:

• Step-by-step instructions
• Procedures or workflows that must be followed in sequence
• Quickstarts

Avoid placing ordered lists inside headings. In procedure-based articles (such as How-To guides), prefer not to use ordered lists because headings already imply sequence. Use ordered lists only when numbering meaningfully improves clarity (for example, in Quickstarts or when strict step order must be emphasized).

Unordered Lists

Use unordered lists for:

• Related items where sequence doesn’t matter
• Features, options, requirements, or considerations

Avoid deeply nested lists. If a list requires more than two levels of indentation, rewrite or restructure the section.

Definition-Style Bullet Points

Use definition-style bullets when listing:

• UI fields
• Configuration terms
• Components
• Requirements
• Conceptual labels

Use the following rules for definition-style bullet points:

• Start every bullet with a bold term followed by a colon. For example, * **Name:** A unique name for the component.
• The description begins with a capital letter.
• Use a single space after the colon.
• Do not use en dashes or em dashes.
• Do not add a period after the bold label unless it is a complete sentence.
• Avoid lists that mix complete sentences and sentence fragments.
• Keep formatting consistent across all products and documentation.

Tables

Use Markdown tables for structured reference information, including:

• Plan details
• Model and version matrices
• Feature comparison tables

Tables provide better scannability and clarity than complex or deeply nested lists.