Do you distinguish keywords from surrounding content?
Last updated by Jayden Alchin [SSW] over 1 year ago.See historyWe've all missed a piece of a message and found out later that we'd got it wrong. This can lead to miscommunication, mistakes, and lost time. Even worse, when finding out later that someone has misread something, there can be a lot of work to fix! But, there are ways to prevent this.
It's important to clearly differentiate keywords and referenced text from your own content to help readers follow the message and avoid confusion.
"We found that moving CodeAuditor's scan engine to be hosted on GitHub Action is not feasible."
Figure: Bad example - It's possible to miss the word 'not'
"We found that moving CodeAuditor's scan engine to be hosted on GitHub Action is not feasible."
Figure: Good example - The bolding draws attention to the main idea, which is 'No'!
When highlighting items (file names, user commands etc.) be sure to:
- Distinguish the items from the rest of the surrounding text
- Be consistent
Warning: Never underline the text if it is not a link. More info on Do you use underlines only on links?
Use the following rules to highlight items in your document:
| Style | Use this style for | Example |
|---|---|---|
| Bold text | Menus, commands, dialog box options, file names and paths | To access the application, click Start | Programs | Accessories | System Tools | Disk Defragmenter |
| Initial Capitals + Bold | File paths and file names | Now open C:\My Documents\Invoice.doc |
| "Quotes" | Exact reference, buttons, labels + Quoting others | Click "Submit" to complete the form. / Make sure your calendar is set to "Out of Office". / Einstein said it best: "If you can't explain it simply, you don't understand it well enough." |
| Different colour styling | Web UI - Important words on headings | Want to build an Angular application? |
| UPPER CASE | Code keywords and database elements | Use the INNER JOIN clause in SQL Server to join one table to another. |
Monospace (i.e. Courier New font) |
Code samples, error messages | You will see the following error: error opening database: database is currently in use. |
Note: If you're quoting longer sentences, such as when replying in an email, it's best to break the line and use clear visual indicators - like indentation, quotation marks, or a different text styles - so the quoted content is clearly separated from your own content.
- Reference - Do you use the correct symbols when documenting instructions?
- Numbers - Do you use separators to improve numbers' readability?
- Do you make awesome documentation?
- Do you format quotations to stand out from the main text?
- Do you know how to format UI elements in technical documentation?
- Do you use indentation for readability?
- Reference - Do you use the correct symbols when documenting instructions?
- Numbers - Do you use separators to improve numbers' readability?
- Do you make awesome documentation?
- Do you format quotations to stand out from the main text?
- Do you know how to format UI elements in technical documentation?
- Do you use indentation for readability?