UX Writing and Terminology

Overview and Patterns

We strive for UI text that is as clear and concise as possible, while giving users the right amount of information to help them get their jobs done. 

Best Practices

• Be concise. 
• Write in the present tense.

• Use numerals (e.g. 1, 2, 3) instead of spelling out numbers.
• Write with direct, simple language that is easy to understand. Make sure your writing communicates only the essential details and is written for all reading levels. 
• Our styles, patterns, and vocabulary are based on US English, which is the default language for Opus Ensemble (e.g. Acknowledgment, not Acknowledgement). However, take localization into careful consideration for all of your writing decisions.

Writing Style

Our writing style is friendly and direct while remaining professional. The majority of our users work in supply chain industries, so we want to make sure the content is as direct and clear as possible to help our users get their jobs done efficiently and effectively, which results in user trust in the software and documentation we provide.

Point of View

• Use second person (i.e. you and your) where it makes sense to do so. However, always ask yourself if using second person provides more value than the more neutral and professional third person. Do not use second person when the action users are taking is on behalf of their entire company, because second person could be confusing in this situation, especially once localized.

• Avoid using first person (i.e. me, my) except for screen titles related to the user's profile. 
• Never combine first and second person in the same sentence or phrase.

Capitalization

• Use title case for all titles and labels within the experience.

• Use sentence case for all assistive text.

Other Sources

For any guidelines not covered in this guide, we refer to the Microsoft Writing Style Guide. 

UI Text Patterns

UI text refers to any text that displays on the screen. This includes but is not limited to titles, labels, assistive text that explains concepts on the screen, buttons, confirmation messages, snackbars, and alt text for images. 

Side Menu Labels

The side menu displays submenus and menu items that are grouped within submenus.

Submenu Labels

• There are no restrictions on what you can name submenus, but be sure to target the business segment (e.g. MAH, CMO, 3PL) and the use case context where similar objects will be grouped to fulfill those use cases.

Menu Item Labels

• Menu items (including subtypes) must be tied to a primary object and must be labeled accordingly.
• When labeling menu items for primary objects, be sensitive to who the persona is and what role they play in the relationship and context of that app. Capture the appropriate directionality. For example, a user from an Owner may perceive a transaction as being “sent”, while a Partner may perceive that same transaction as being “received”.

Screen, Section, Push Panel, Dialog, and Component Titles

Standard Screen Titles

The screen type determines the pattern used for the screen title.

• For Search screens, the title of the screen must be “Search [Menu Item]”, where [Menu Item] is the side menu item associated with the Search screen. For example, if users select the Purchase Orders menu item, the screen they land on must be titled Search Purchase Orders.

• For View/Edit screens, use the following pattern: “[Object Type Name] Details.” For example, if users select a purchase order while on the Search Purchase Orders screen, the screen they land on must be titled Purchase Order Details. If they choose to edit that purchase order, the screen changes from view mode to edit mode and the screen title remains Purchase Order Details.

• For New screens, use the pattern: “New [Object Type Name].” For example, if users select the New button while on a Search Purchase Orders screen, the screen they land on must be titled New Purchase Order.
• Use action-oriented titles for all screens.
• Avoid punctuation in screen titles.

Push Panel Screen Titles

• When users are exporting data from the system, use "Export [Object Types]" (e.g. Export Incidents) as the push panel title.
• When users are adding a new item to a collection, use "New [Field Name]" (e.g. New Line Item).
• When users are performing other actions (e.g. editing or removing a collection item), use "[Action] [Field Name]” (e.g. Edit Line Item or Remove Line Item). For guidance on the wording of actions, see the Vocabulary section.
• For view-only (or view as the primary purpose) push panels, use “View Details” as the title with no other words. Do not include the object name.

• Avoid punctuation in push panel titles.

Dialog Screen Titles

• The only use case for a dialog is when changing from edit mode to view mode without saving changes, to alert users that their changes will be lost. Use “Unsaved Changes”.
• Avoid punctuation in dialog titles, even for confirmation actions.

Other Component Titles

• Spell out "Identifier" in collection names. Use “ID” for field names. This provides for more horizontal space without losing clarity.
• For steps within a Progress Indicator:
  • The title of each step in the Progress Indicator should follow the pattern "Step [Numeral]: [Workflow State of Object Type]" (e.g. Step 1: Pending, Step 2: Prepare Inbound, Step 3: Process Inbound, Step 4: Prepare Outbound, Step 5: Process Outbound).
  • The section headers within each step should match the workflow state from the step title (e.g. Submit, Processing, Processed, Preparing To Send, Sending). 

Button Labels

• Use active verbs as the labels for all buttons. The exception is “New,” which is used instead of “Create.” See the Vocabulary section for specific verbs and how we use them.
• Use verbs that indicate what the user actually wants to accomplish (e.g. New, View), instead of generic button labels (e.g. Submit).
• Keep button labels to one word. If buttons need more clarification, you can use additional words in the alt text. However, always use the title of the screen, dialog, or push panel to clarify first.

Action Icons and Menu Labels

• Use active verbs as the labels. See the Vocabulary section for specific verbs and how we use them.
• Use verbs that indicate what the user actually wants to accomplish (e.g. View, Edit), instead of generic labels (e.g. Manage).

• Any nouns included in the label must be singular, not plural, even if users can take action on multiple objects at once. The exception to this is Search page headers (e.g. Search Purchase Orders).

Field Labels

• The shortest label is ideal. Avoid labels that use multiple nouns, unless they all provide explicit value. For example, in Supplier Name, Name is an extraneous noun because Supplier gives users all of the relevant information.
• Do not include punctuation, even on toggles with Yes and No values.

Dates

• For fields that represent dates in the past, use "Date [Action]ed" instead of  "[Action] Date." The exceptions to this rule are "Expiration Date" and "Event Date" because these are supply chain industry terms.

• For fields that represent due dates in the future, use "[Noun] Due Date" instead of "Date [Noun] Due."

• Date and time values should always display in the following formats: 
  • Date –  DD Mmm YYYY
  • Date and Time – DD Mmm YYYY HH:MM AM/PM
  • Date, Time, and User – DD Mmm YYYY HH:MM AM/PM by [User Name]

Workflow States

• For workflows with 3 states, the default workflow state names could be "To Do," "In Progress," and "Done." 
• For workflows with more than 3 states or workflows that require more specific names, name all but the final state using active verbs or adjectives that describe what is happening while the object is in that state. For the final state name, use a verb in the past tense.

• Avoid deviating from the default state names if the new name does not bring additional meaning to the state. For example, Not Started is extremely similar to To Do, and does not provide additional clarity or specificity. However, In Review is clearly more specific and provides additional meaning than In Progress.

Confirmation Messages

• For operations users can do in a push panel that require a confirmation before proceeding (e.g. removing an object), use:
  • Push Panel title: Remove [Object]
  • Message 1st line: “The [object] will be removed and cannot be retrieved.”
  • Message 2nd line: “Remove this [object]?”
  • Buttons: Cancel | Remove

Snackbars

• For system errors that users cannot do anything about, use this generic message: "Something went wrong. Try again later. If the issue continues, contact [App Provider name, and the name of their support department if available]."
• For messages that contain a list of values:
  • Write the message as a stem sentence that introduces the list of values. 
  • Use a colon at the end of the stem sentence. 
  • Do not include a period at the end of the list or a conjunction (i.e. and, or) prior to the last value. 

Success Messages

• For synchronous actions, use this pattern: "The [specific name] [object type] is [action in past tense].”

• For asynchronous actions (e.g. exporting data that takes time before it is available), use this pattern: "[App Provider Name] is [action]. [Description of how users know when the action is complete or where to find the result]." 
  • For asynchronous export actions, use this pattern: "[App Provider Name] is exporting the [File Name] file. The file will be available in your notifications when it is ready."
• The Opus Platform backend initially writes new and updated data to a different database than the platform reads data from, which allows for high availability during app deployments. This functionality means that when users update the UI, they might not see their updates immediately, but they will see their updates momentarily (in under one minute). Because the updates display in under one minute, these actions are not truly asynchronous. Add these sentences to your confirmation messages when users land on a screen where they expect to see the updates they just made:
  • For adding an object when redirected to the Search screen: "[success message]. The new [object type] will display shortly." 
  • For editing an object while on the [Object Instance] Details screen: "[success message]. The updates for this [object type] will display shortly."
  • For removing an object while on the Search screen or while on the [Object Instance] Details screen and then redirecting to the Search screen: "[success message]. The [object type] will stop displaying shortly."
  • For changing an object status while on the Search screen or while on the [Object Instance] Details screen and then redirecting to the Search screen: "[success message]. The new [object type] status will display shortly."
  • For adding a related object while on the [Object Instance] Details screen of an existing object: "[success message]. The new [object type] will display shortly."
  • For editing a related object while on the [Object Instance] Details screen of an existing object: "[success message]. The updates for this [object type] will display shortly."
  • For removing a related object while on the [Object Instance] Details screen of an existing object: "[success message]. The [object type] will stop displaying shortly."
• System-generated IDs should not be used in success messages for Add actions. These success messages should only include values from the form the user has just filled out.
• If users are not currently on or are redirected to the screen where the new or updated information should display and must navigate to a different screen to see that information, the extra sentence in the success message is not needed because the information will display by the time users search for and find it. For example, you might have a form that refreshes with blank fields when users select Apply, and then users must navigate back to the Search screen and enter filter criteria before any results display. By the time they find the object they are looking for, the information will be updated and reflect accurately on the screen.

Error Messages

• For required fields that are left blank, use the following generic message: “One or more required fields is not filled in." 
  Ideally, required fields that are left blank should be indicated with a field-level error instead of a snackbar error message. Use this field-level error if field-level errors are available or for errors in API responses: "[Field Label] is required."
• State the error that occurred in the first sentence, and then in a second sentence, state why the error occurred. If possible, phrase the second sentence as an instruction that explains what users must do to correct the error.

• If you refer to a specific value, capitalize the field label as a proper noun and place the field label (e.g. Purchase Order) in front of the value (e.g. [PO Number]).

Notifications

Notifications are available in the Notifications push panel and by email. 

Notifications Push Panel

Each notification displays the following information:

• Title ("Notifications")
• Sender (e.g. Solution name)
• Subject (e.g. Business Object name)
• Message
• Link to the subject in the form "View Details" which opens the respective solution or network frame in a new Opus tab
• Timestamp when created:
  • If less than 24 hours ago - “[N] hours ago”
  • If more than 24 hours but less than 2 days - “1 day ago”
  • If more than 2 days but less than 7 days - “N days ago”
  • If between 14 days and 21 days - “2 weeks ago”
  • If between 21 days and 30 days - “3 weeks ago”
  • If between 30 days and 59 days - “1 month ago”
  • If more than 59 days - “[N] months ago”
    • N = ([Number of Days since created]/30) rounded down to nearest integer

Email Notification

For the email notification:

• Subject – Your [Solution Provider Name] [File Type] File is Ready
  • Subject lines should always be in title case, without end punctuation.
• Body – 
  The [App Name] [file type] file you requested on [Timestamp: DD Mmm YYYY HH:MM] is now available:
  [Link to the file in the form of the file name]

Assistive Text

Assistive text is UI text that provides users with guidance, rather than labeling a UI element. Include assistive text for screens, sections, push panels, dialogs, and components when it is useful. Do not include assistive text if it does not provide real value (i.e. the screen, section, push panel, dialog, or component is self-explanatory even to new users).

Screen-Level

• Use punctuation at the end of the sentence, even if the assistive text only consists of one sentence. 
• When users are confirming an action in a push panel (e.g. removing an object from the system), use this pattern: "[Implications of action, including the specific object being acted on]. [Action] this [object]?"

• When users are importing data:
  • Use this pattern: "Select a file containing [contents of file] to [action being taken with the imported data]. Match the CSV's format to the following sample: [Object]Sample.csv" 
    • For example: "Select a file containing review information to add or modify. Match the CSV's format to the following sample: PurchaseOrderSample.csv"
  • The sample CSV file name should have a link that downloads an example file when selected. 
  • Don't include a period at the end of the second sentence. 

Empty States

• For searches with zero results, use this generic message: "No results found. Try modifying the search criteria."
• For components that do not have any data, and where users cannot modify search results, use this generic message: "No data available."
• For components that do not have any data because nothing has been added yet (i.e. first-time messages), use this pattern: "No [objects] are currently [verb or description]."

Vocabulary

We chose these words so that our UI text is consistent across all experiences. Make sure you also use consistent word choices across your experience for anything not covered here.