Skip to main content
Version: On prem: 15.0.2

Procedures and instructions

Learn the secrets behind creating message templates that resonate with your audience and convey your message with impact.

Text formatting​

Bold:

  • Buttons

  • Markup language elements (tags)

  • Omada Identity

  • Guide’s name

  • UI elements

  • Fields

  • Forms

Italic:

  • New terms

  • Setting values (True/False)

  • Emphasis.

UI message templates​

Use the following guidelines whenever you need to write a message in the UI:

My message:

  • Is clear

  • Uses a positive tone

  • Uses present tense

  • Has concise description

  • Suggests actions

  • Avoids technical jargon

  • Answer these questions:​

    • Who or what is doing the action?​

    • What will happen?​

    • How to avoid it?​

  • K.I.S.S rule (Keep it Simple, Stupid)

Type of messageDescriptionExample
SuccessTitle: Operation Successful
Message: You successfully completed the [operation/task].		You successfully added an object to the whitelist of allowed modifications and deletions.
ErrorTitle: 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.
WarningTitle: Warning
Message: [Warning message describing the issue or potential problem. State the outcome].		This is a template object. Do you want to delete it?
InformationalTitle: Information
Message: [Information or instructions relevant to the current task or situation].		Please enter a valid email address to continue with the registration process.
ConfirmationTitle: 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​

When composing instructions, which often consist of multiple steps presented in a numbered list, ensure to follow these guidelines:

  • Use heading in Present Simple: Employ a heading written in the Present Simple tense to aid customers in quickly locating instructions, such as Create resource assignment.

  • Consistent formatting: Format procedures consistently throughout the document to facilitate easy navigation for users.

  • Numbered entries: Utilize a separate numbered entry for each step to maintain clarity and organization.

  • Complete sentences: Construct each step as a complete sentence for better understanding.

  • Imperative verb forms: Employ imperative verb forms to provide clear and concise instructions, e.g., Enter a file name, and then save the file.

  • Consistent sentence structures: Maintain consistency in sentence structures to enhance readability and comprehension.

  • Period after each step: End each step with a period to signify its completion.

Single-step instruction

For single-step instructions, maintain 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

Release Notes​

When composing release notes, adhere to the following guidelines:

  • Introduction header: Present a concise overview of the changes introduced.

  • Simplified language: Use straightforward, easily understandable words and phrases, avoiding excessive technical jargon.

  • Documentation link: Include a hyperlink directing users to detailed documentation for further information on the newly introduced features.

  • Visual aids: Incorporate screenshots to effectively capture users' attention and enhance comprehension.

  • Avoid politeness indicators: Omit the use of "please" in release notes for a professional tone.

Bugs & known issues​

When documenting bugs and known issues, ensure to cover the following aspects:

  • Introduction header: Provide a brief overview of the bug.

  • Problem description: Clearly describe the issue encountered.

  • Implemented fix description: Explain the solution or fix that has been implemented.

  • INC number: Include the unique INC number assigned to the issue in the Fresh service.

note

Remember, if the development team introduced new settings, features, or made significant changes during bug fixing, update the documentation accordingly and provide users with the relevant link.