Use the following conventions to format text that refers to common elements such as GUI elements, programming code, new terms, and so on.
Using these conventions is important as it provides an easy and consistent way for readers to identity what the text is about.
Formatting Conventions
| Element |
Format Details |
Names, titles, or labels of UI elements:
- Buttons
- Menus
- Tabs
- Menu and tab choices
- Commands on menus, toolbars, or ribbons
- Windows
- Dialog boxes
- Dialog box options
- Icons
- Panes
- Wizards
- Views
- etc.
|
- Render in bold.
- Preserve the capitalization of the original UI element.
|
References to programming code:
- Classes
- Properties
- Events
- Methods
- Objects
- Variables
- Operators
- etc.
|
- Render in
monospace.
- In Markdown, enclose in back quotes (graves,
``), which produces HTML code tags.
|
|
Command lines
|
- Render in
monospace.
- Render parts that the user needs to enter verbatim in
bold:
- Command names
- Keywords and punctuation that is part of a command
- Command options
- Command switches
- Render parts that the user needs to enter in an environment-specific way in
italic:
- Arguments
- File paths
- Answers to prompts in interactive commands
- Render command prompts in regular monospace font.
- Render command output in a regular monospace font.
- In Markdown, enclose in back quotes (graves,
``) or triple back quotes (``` ```) to produce HTML <code> or <pre><code> </pre></code> tags.
- Examples
|
References to command lines in text:
- Commands
- Options
- Parameters
- Paths
- Command output
- User input
- etc.
|
- Render in
monospace.
- Do not use commands as verbs.
- In Markdown, enclose in back quotes (graves,
``), which produces HTML <code> tags.
- Examples
- Use the
show running-config command to display the results.
- Not so good:
cd to the root folder.
- Much better: Use the
cd command to go to the root folder.
|
References to system resources:
- Data types
- File extensions
- Files
- Directories/Folders
- Paths
- Error messages
- Markup language elements
- Tags
- Registers
- Registry settings
- Statements
- User input
- Values
- Database names
|
- Render in
monospace.
- In Markdown, enclose in back quotes (graves,
``), which produces HTML <code> tags.
|
- Code snippets
- Code blocks
|
- Render in
Monospace.
- In Markdown, enclose in triple back quotes (graves,
``` ```), which produces HTML <pre><code> </pre></code> tags.
- Preferably, add the snippet language after the opening triple back quotes:
```JavaScript. This adds the lang attribute: <pre lang="JavaScript"><code> </pre></code>.
|
References to keyboard keys:
- Separate keys
- Key combinations
- Key sequences
|
- Render in
monospace, Initial Caps.
- Use the plus sign (
+) for key combinations. Type in monospace as well. No spaces around the plus sign.
- Examples
- Press
Y at the prompt to agree.
- To refresh the page, press
Ctrl+R.
- To enable transdimentional travel, press
Ctrl+T and then press Ctrl+D.
|
|
Logical operators
|
- Render in regular font, ALL UPPERCASE.
- If the logical operator is a part of a programming language syntax, use monospaced font.
- Examples
|
|
New terms (when introduced in an article or a chapter)
|
- Render in Italic, no quotes.
- Use sparingly, only when emphasis is needed.
- Examples
- When the relation is not stored in the current content type, it is called an external relation.
|
Names of third-party:
- Programs
- Utilities
- Frameworks
- Tools
- Product names
|
- Use regular font, no formatting. Preserve the original spelling.
- Check the third-party trademark list for proper spelling. Use variables when possible to ensure consistency between mentions.
|
|
Sequences of commands on menus, toolbars, or ribbons
|
- Use bold for the commands.
- Separate with the greater than sign (
>) in regular font. Use spaces all around.
- Note: In Markdown, you may need to escape the sign using an HTML entity:
>.
- Examples
- Open Tools > Options and then click Fonts.
- Go to Notifications > Push notifications > Devices.
|
|
Units of measure
|
- Use the same formatting as for paragraphs or characters.
- Type units exactly as defined by the SI.
- Leave a space between the value and the unit.
- Examples
|