Procedures and instructions
Learn how to format text in instructions, write UI messages, and structure procedures, release notes, and known issues.
This page summarizes the Microsoft Style Guide, which is our only source of truth. If you're in doubt, check it and follow it.
Text formatting
This formatting applies to documentation. In UI text, avoid bold and italic formatting.
Bold:
-
Names of UI elements when you must refer to them, such as buttons, checkboxes, boxes, menus, tabs, dialogs, and panes. Don't include end punctuation from the UI label, such as a colon or an ellipsis.
-
Key names and keyboard shortcuts, for example, Ctrl+Shift+P
-
UI paths, for example, Setup > Systems
-
File and folder names, when you tell the user to select or enter them
-
Text that you tell the user to enter, for example, Enter hello world.
Code style:
-
Markup language elements (tags), for example,
<img> -
Commands, code, and file paths in code
Italic:
-
New terms, on first mention, when you define them immediately
-
Placeholders, for example, Enter password.
-
Setting values (True/False)
-
Names of sections, documents, and guides
-
Emphasis (use sparingly)
Quotation marks:
- Error messages that you refer to in text, for example, If you see the error message "Check scanner status and try again," ...
UI message templates
Use the following guidelines whenever you need to write a message in the UI.
Make sure that your message:
-
Is clear
-
Uses a positive tone
-
Uses the present tense
-
Is concise
-
Suggests actions
-
Avoids technical jargon
-
Answers these questions:
-
Who or what is doing the action?
-
What will happen?
-
How can the user avoid it?
-
-
Follows the KISS rule (keep it short and simple):
Don't write Write Revert back to your home page Back to home page Make changes to your home page Edit Please, retry later Try again later Please, fill in the required attributes to continue Fill in the required attributes You will be able to add or edit the resources attributes You can add or edit the attributes of the resource
Avoid please in UI messages. Use it only when you ask the user to do something inconvenient or when the product is to blame for the situation, for example, "The connection was lost. Please sign in again."
| Type of message | Description | Example |
|---|---|---|
| Success | Title: Operation successful Message: You successfully completed the [operation/task]. | You successfully added an object to the allow list of modifications and deletions. |
| Error | Title: Error encountered Message: An error occurred while [description of the task/operation]. Try again later or contact support for assistance. | You need to have one of these roles: business manager, role owner, or system owner to use this control. |
| Warning | Title: Warning Message: [Warning message describing the issue or potential problem. State the outcome.] | This is a template object. Do you want to delete it? |
| Informational | Title: Information Message: [Information or instructions relevant to the current task or situation.] | Enter a valid email address to continue with the registration. |
| Confirmation | Title: Confirm [action/operation] Message: Are you sure you want to [perform the action/operation]? This action can't be undone. | Are you sure you want to delete this item? This can't be undone. |
Procedure documentation
Step-by-step instructions
Instructions often consist of multiple steps in a numbered list. When you write them, follow these guidelines:
-
Headings: Use a heading that concisely describes what the instructions help users do, so that they can find the instructions quickly. Start the heading with an imperative verb and use the same structure in all headings, for example, Create a resource assignment and Add an account.
-
Introductory sentence: If you add an introductory sentence, make sure that it adds information and doesn't just repeat the heading.
-
Consistent formatting: Format procedures the same way throughout the documentation.
-
Numbered steps: Use a separate numbered step for each instruction. It's OK to combine short steps that happen in the same place in the UI.
-
Location first: Make sure that users know where the action takes place before you describe the action, for example, On the Design tab, select Header row.
-
Complete sentences: Write each step as a complete sentence. Capitalize the first word.
-
Imperative verbs: Start each step with an imperative verb, for example, Enter a file name, and then save the file. If users need to start in a specific place, begin the step with a short phrase that says where.
-
Completion actions: Include the action that completes the procedure, such as selecting OK or Apply.
-
Period after each step: End each step with a period.
For single-step instructions, use the same format but replace the number with a bullet.
Simple instructions
Abbreviate simple sequences by using right angle brackets. Include a space before and after each bracket, and don't make the brackets bold, for example:
Setup > Systems or Services > Systems
Use this approach only when the path through the UI is clear and the selection method is the same for each step.
Screen readers might skip the > character and read a path such as Setup > Systems as "Setup Systems," which can confuse users. For complex paths, write out the steps instead.
Release notes
When you write release notes, follow these guidelines:
-
Introduction header: Give a short overview of the changes.
-
Simple language: Use plain words and phrases, and avoid technical jargon.
-
Documentation link: Add a link to the detailed documentation about the new features.
-
Screenshots: Add screenshots to help users understand the changes.
-
No "please": Don't use please in release notes.
Bugs and known issues
When you document bugs and known issues, cover the following:
-
Introduction header: Give a short overview of the bug.
-
Problem description: Clearly describe the issue.
-
Fix description: Explain the fix that was implemented.
-
INC number: Include the unique INC number assigned to the issue in Freshservice.
If the development team introduced new settings or features, or made significant changes while fixing a bug, update the documentation and give users the relevant link.
Third-party references
Third-party products, services, and documentation can change independently of Omada. Adding this disclaimer helps readers understand that some information may become outdated and tells them how to report inconsistencies.
When a page includes references to third-party products, services, or documentation, add the following disclaimer near the beginning of the page:
This page contains third-party references. We strive to keep our content up to date, but information about external vendors may change independently of Omada. If you spot any inconsistencies, report them through the support channel.