Writing

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.

• Be concise.
• Write in the present tense.

  The film review is saved.

  Do

  The film review has been saved.

  Don't

• 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. However, take localization into careful consideration for all of your writing decisions.

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. Using second person when the action users are taking is on behalf of their entire company is not helpful and could even be confusing, especially once localized.

  Your settings are saved.

  Do

  Use second person when the action users are taking is specific to themselves.

  Your incident is saved.

  Don't

  Don't use second person when the action users are taking is on behalf of their entire company or location.

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

Capitalization

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

  View Film Review

  Do

  View film review

  Don't

• Use sentence case for all assistive text.

  Specify the film you want to review.

  Do

  Specify the Film You Want To Review.

  Don't

Other sources

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

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, banner messages, and alt text for images.

• Experience tasks within the Do menu item must use action-oriented labels (e.g. "Monitor Film Reviews").

  Monitor Film Reviews

  Do

  Film Reviews

  Don't

Standard screen title

• Match the title of the screen linked from the side menu to the name of the experience task so that the breadcrumbs align with the experience task. For example, if users select the Monitor Film Reviews experience task, the screen they land on must also be titled Monitor Film Reviews.
• Use action-oriented titles for all screens.

  Review All About Eve

  Do

  All About Eve Review

  Don't

• When users are exporting data from the system, use "Export [Object Types]" (e.g. Export Film Reviews) as the section title. For more information on using export and download, see Consistent word choices.

• For view details screens:
  • Use "View [Object Type] [ID]" if the object users are viewing has a system-generated identifier.

    View Film Review GH-1234

    Do

    View GH-1234 Film Review All About Eve

    Don't

  • Use "View [Object Type]" when users might not have enough context to remember what object type they're viewing by looking at the specific name of the object alone. In the example below, View All About Eve could be displaying the details of the film itself or of the film review.

    View Film Review

    Do

    View All About Eve

    Don't

  • Use "View [Specific Object Name]" when users have enough context to understand exactly what object type they're viewing just by looking at the specific name of the object.

Panel screen titles

• When users are adding a new object to the system, use "New [Object Type]" (e.g. New Film Review).
• For view-only (or view as the primary purpose) overlay panels, use the actual name of the object being viewed or the object type and identifier as the title, with no other words.

  Jane Smith

  Do

  Jane Smith Details

  Don't

  Film Review GH-1234

  Do

  View GH-1234 Film Review All About Eve

  Don't

• For overlay panels where the primary purpose is to perform an action, follow the same rules as a screen.
• For links to view the full details of an object within the title bar of an overlay panel, use "View Details".

Dialog screen title

• Use "[Action Verb] [Object Type]" for all dialog titles.
• Avoid punctuation in dialog titles, even for confirmation actions.

  Remove Review

  Do

  Remove Review?

  Don't

Other component titles

• Spell out "Identifiers" in section headers if the entire section header is only that word. Use "IDs" if there is an adjective.

  Reviewer IDs

  Do

  Reviewer Identifiers

  Don't

• For the steps within a Progress Indicator:
  • The title of each step in the Progress Indicator uses the following pattern: "Step [Numeral]: [Object Type]" (e.g. Step 1: Film, Step 2: Review, Step 3: Reviewer Bio).
  • The section headers within each step should match the noun from the step title (e.g. Film, Review, Reviewer Bio).

• Use active verbs as the labels for all buttons. See Consistent word choices for specific verbs and how we use them.
• Use verbs that indicate what the user actually wants to accomplish (e.g. Add, Copy), instead of generic button labels (e.g. Submit).

  

  Do

  

  Don't

• Keep button labels short, preferably one word. If necessary, 2 words or 3 words with one word being a short preposition can be used. However, always try first to clarify with the title of the screen, dialog, or panel first, rather than in the button label. Usually, more than one word is necessary only when you place a secondary button next to a primary button and need to differentiate the function of each.

  

  Do

  

  Don't

  

  Do

  

  Don't

  

  Do

  

  Don't

• Labels for action icons and menu items follow similar patterns as button labels:
  • Use active verbs as the labels. See Consistent word choices for specific verbs and how we use them.
  • Use verbs that indicate what the user actually wants to accomplish (e.g. Edit, Copy), instead of generic labels (e.g. Manage).
• Include the noun in the label if the object that the user is acting on isn't immediately clear from the context. For example, in table rows, if all menu items are acting on the object represented in the row, you don't need to include the noun. However, if some of the menu items are acting on the object represented in the row and some of the menu items are acting on objects or data related to that object, then you need to include the nouns.

  Edit, Remove

  Do

  Edit Review, Remove Review

  Don't

  Edit Review, View Activity History, Remove Review

  Do

  Edit, View Activity History, Remove

  Don't

• Any nouns included in the labels must be singular, not plural, even if users can take action on multiple objects at once.

  Add Review

  Do

  Add Reviews

  Don't

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

  Correct Review Information

  Do

  Correct Review Information?

  Don't

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.

  Date Released

  Do

  Release Date

  Don't

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

  Review Due Date

  Do

  Date Review Due

  Don't

• 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

• The default workflow state names are "To Do," "In Progress," and "Closed".
• If you have workflow states that would benefit from more specific names, or you need to add additional workflow states to your object, 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.

  Under Investigation, In Review, Pending Approval

  Do

  Investigating, Reviewing, Approving

  Don't

  Closed

  Do

  Complete

  Don't

• 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, so there isn't a reason to introduce inconsistency. However, In Review is clearly more specific and provides additional meaning than In Progress, yet applies to all of the review objects.

Role names

• Don't use the app or solution name in the role name.
• Roles specifically for configuring and setting up the app or its networks are Administrators and should use the following pattern: "[Object] Administrator" (e.g. Application Administrator, Network Administrator, Team Administrator).
• Roles for end users use the following pattern: "Member – [Type of access] Access".

  Member - Expanded Access

  Do

  Full Member

  Don't

• Keep the Member role names as simple as you can. If possible, use the following role names:
  • "Member - Expanded Access" for roles with access to all functionality.
  • "Member - Standard Access" for roles with access to some functionality, including add and edit actions.
  • "Member - Read-only Access" for roles with read-only access to the data.

• 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.

  The new reviews for the following films are added: All About Eve, An American in Paris, Argo

  Do

  The new reviews for the following films are added: All About Eve, An American in Paris, and Argo.

  Don't

Confirmation messages

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

  The Not Worth the Money review is added.

  Do

  Your review has been added.

  Don't

• 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 writes new and updated data to a different database initially 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: "[confirmation message]. The new [object type] will display shortly."
  • For editing an object while on the View Details screen: "[confirmation message]. The edits for this [object type] will display shortly."
  • For deleting an object while on the Search screen or while on the View Details screen and then redirecting to the Search screen: "[confirmation message]. The [object type] will stop displaying shortly."
  • For changing an object status while on the Search screen or while on the View Details screen and then redirecting to the Search screen: "[confirmation message]. The new [object type] status will display shortly."
  • For adding a related object while on the View Details screen of an existing object: "[confirmation message]. The new [object type] will display shortly."
  • For editing a related object while on the View Details screen of an existing object: "[confirmation message]. The edits for this [object type] will display shortly."
  • For deleting a related object while on the View Details screen of an existing object: "[confirmation message]. The [object type] will stop displaying shortly."

  System-generated IDs cannot be used in confirmation messages for Add actions. These confirmation messages can only include values from the form the user has just filled out.

  If users are not currently on or 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 confirmation message is not needed because the information will display by the time users search for and find that information. For example, you might have a form that refreshes with blank fields when users select Submit, 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.

• Cancel actions do not require confirmation messages.

Error messages

• For required fields that are left blank, use the following format: "[Field Label] is required."

  Ideally, required fields that are left blank should be indicated with a field-level error instead of a banner error message. Use this banner message if field-level errors are unavailable or for errors in API responses.

• State the error that occurred in the first sentence, and then in a second sentence, state why the error occurred. Phrase the second sentence as an instruction if that is useful to understanding what users must do to correct the error.

  Actor Bette Davis is set as the lead. Set another actor as the lead to remove her from this review.

  Do

  Cannot remove Actor Bette Davis.

  Don't

• If you refer to a specific value, capitalize the field label as a proper noun and place the field label in front of the value.

  Release Market Germany is added multiple times. Only one review for each release market can be entered.

  Do

  Remove duplicate release markets for this review.

  Don't

Email notification subject lines should always be in title case, without end punctuation. For example: Your Review is Approved

File export notifications

For the Notifications panel:

• Title – Your [File Type] File is Ready
• Content –

  The [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]

For the email notification:

• Subject – Your [App Provider Name] [File Type] File is Ready

• 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 is UI text that provides users with guidance, rather than labeling a UI element. Include assistive text for screens, sections, and components when it's useful. Don't include assistive text if it does not provide real value (i.e. the screen, section, 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 (e.g. removing something from the system), use this pattern: "[Implications of action, including the specific object being acted on]. [Action] this [object]?"

  The review for the 1951 film All About Eve will be lost and cannot be retrieved. Remove this review?

  Do

  Are you sure you want to remove this review? It will be lost and cannot be retrieved.

  Don't

• 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"
    • E.g.: "Select a file containing review information to add or modify. Match the CSV's format to the following sample: ReviewSample.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.

Field-level

• In field-level assistive text, when specifying the maximum character count for a field, use the pattern: "[Number] characters max".

  100 characters max

  Do

  Maximum 100 characters

  Don't

• Avoid full sentences unless absolutely necessary.

  In the film's original market

  Do

  Enter the distribution date for the film's original market

  Don't

• Avoid periods or other end punctuation.

  In the film's original market

  Do

  Enter the distribution date for the film's original market.

  Don't

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 as been added yet (i.e. first-time messages), use this pattern: "No [objects] are currently [verb or description]."

  No users are currently assigned the Critic role.

  Do

  The Critic role has not been assigned to any users yet.

  Don't

These terms are words specific to TraceLink and the Opus Platform and must be used in the defined contexts.

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.