Writing guidelines

To make your applications clear and easy to understand, follow these simple writing guidelines. For issues not covered below, refer to the Microsoft Style Guide and the Plain Language Guidelines.

Voice

Text should be direct, professional, and conversational. Use simple and common terms.

  • Poor label: “Elaborate”, “Modify”
  • Better label: “Describe”, “Edit”

Keep text short and to the point, while being clear. Avoid filler words, such as: “itself”, “quite”, “truly”, “very”, “mostly”, “definitely”, “actual”, and “particular”.

  • Poor label: “Select the particular service the customer needs.”
  • Better label: “Service”

Speak to users as a warm, concise, and empowering business coach when providing descriptions or offering help.

  • Poor content: “You can’t do that. Find the Settings option instead.”
  • Poor content: “Click Settings.”
  • Better content: “To keep working, visit Settings.”

Tone

Be cautious using pleasantries. Save this for initial conversations (such as in a customer service script), unless there is an explicit need to be polite, such as when the user is in a difficult situation and may be frustrated.

  • Poor label: “Please lease refer to the Pega Documentation site.”
  • Better label: “Visit Pega Documentation.”

Avoid using exclamation marks within the UI, especially in error messages.

  • Poor label: “Offline!”
  • Better label: “Offline.”

Avoid using acronyms that are not well-defined within your organization. When in doubt, spell out the full acronym.

  • Poor label: “DB”, “BAP”
  • Better label: “Database”, “Business auto policy”

Don’t use evocative language. Use neutral alternatives instead.

  • Poor label: “Terminate the service”
  • Better label: “Cancel service”

Grammar

Items within a list should follow a consistent pattern. For example, items could begin with a noun or a verb but shouldn’t alternate between the two.

  • Poor label: “Location change, Was not satisfied with provider, Other”
  • Better label: “Location change, Dissatisfaction with provider, Other”

Don’t end nouns with an “(s)” when the noun may be either singular or plural.

  • Poor label: “Select the service(s) to cancel.”
  • Better label: “Select services to cancel.”

Place the word “only” directly before what you want it to modify. Consider how the meaning changes in the following sentences, based on where “only” is placed within them:

  • “Only an administrator can open the XML files.” This means administrators are the only users who can open the XML files.
  • “An administrator can only open XML files.” This means the only thing that Administrators can do is open XML files.

Use colons when introducing a scope, words, or phrases in a sentence.

  • Poor label: “Choose one — red, blue, green, yellow.”
  • Better label: “Choose one: red, blue, green, yellow.”
  • Poor label: “Bugs – Open”
  • Better label: “Bugs: Open”

Use hyphens after prefixes and to connect words in a sentence or phrase, when appropriate.

  • Poor label: “The UX design system provides out of the box components and patterns.”
  • Better label: “The UX design system provides out-of-the-box components and patterns.”

Use en dashes (–) for mathematical purposes instead of a hyphen (as a minus sign, to show negative numbers, to show a range, etc).

  • Poor label: “The school accepts children ages 5-10.”
  • Better label: “The school accepts children ages 5–10.”

Don’t use ampersands, spell out the word “and”.

  • Poor label: “Save & close”
  • Better label: “Save and close”

Capitalization

Use sentence case as the default standard for most non-user generated text in UI.

Use title case for:

  • Proper nouns
  • Application names
  • Case Types
  • Branded product names (such as Pega Platform)
  • Main navigation links and landing page titles (such as Explore Data)
  • Unique Pega concepts (such as Case Designer)

Avoid using all capital letters, as screen readers interpret this as an abbreviation.

Use lower case when spelling out acronyms. Only use title case when the acronym is a proper noun.

  • Poor label: UI (User Interface)
  • Better label: UI (user interface)
  • Better label: CDT (California Department of Technology)

Word choice and sentence structure

With the exception of industry terminology, write all content around an eight grade reading level, as recommended by WCAG 2.2 3.1.5.

  • Poor content: “Utilize the transliterator for optimal throughput.”
  • Better content: “Use the converter for best results.”

Don’t blame users or the application for mistakes. Instead, help fix issues.

  • Poor label: “You are offline.”
  • Better label: “Connection lost. Retry?”

Don’t use emojis, line breaks, or other visual elements in content unless business appropriate.

  • Poor label: ” Pet name “
  • Better label: “Pet name”

Repeat the structure of labels previously mentioned in the UI for consistency, when possible.

  • Poor labels: “Add a vehicle”, “Enter an additional driver”
  • Better labels: “Add vehicle”, “Add driver”

Avoid industry-specific terminology or jargon your users may not be familiar with. Ensure you are using clear, generic terms that are understandable for your audience.

  • Poor label: “Enter any sound bites used to sell the product.”
  • Better label: “Add topics that helped sell the product.”

Avoid using acronyms your users may not know. If using an uncommon acronym, spell out the acronym first.

  • Poor label: “View the ATR.”
  • Better label: “View the average time to respond.”

When referencing a labelled object in the UI, such as an Assignment or Case label, put the label in quotes to improve readability.

  • Poor label: “Merge branch test-branch.”
  • Better label: “Merge branch ‘test-branch’”.

Use fewer words when the input’s purpose is already clear. For example, if a user is picking from options in a radio group, words like “Select” or “Choose” in the label makes it harder to quickly understand the intent.

  • Poor label: “Choose a package from the available options”
  • Better label: “Packages”

Avoid using “could”, “should”, and “would” to avoid ambiguity.

  • Poor label: “The start date should be in the format mm/dd/yyyy.”
  • Better label: “Use the mm/dd/yyyy format for start date.”

Case stages names are locations in the flow, so each should use nouns.

  • Poor label: “Research data”
  • Better label: “Data research”

Assignment names are actions to be taken to progress the flow, so each should begin with a verb.

  • Poor label: “Data collection”
  • Better label: “Collect data”

Writing guidelines for forms

Field labels

For standard inputs, avoid starting field labels with verbs. Instead, simply state the noun.

  • Poor label: “Provide accident details”
  • Better label: “Accident details”

However, for checkboxes, start the label with a verb.

  • Poor label: “Label visibility”
  • Better label: “Hide label”

Input labels are easier to understand as statements instead of questions. Use questions sparingly, such as in customer service contexts. Avoid mixing statements with questions.

  • Poor labels: “What is the reason for your payment?, Payment method”
  • Better labels: “Reason for payment, Payment method”

When writing field label text, be specific about what the field is collecting from the user.

  • Example: Address input fields should specify which address to enter: “New address” or “Previous address”.

Use fewer words or characters in your labels, as long as doing so doesn’t alter meaning.

  • Poor label: “Enter the details found on your card”
  • Better label: “Card details”

Displaying supplemental information

Use form instructions to provide general instructions for how to complete a form flow.

  • Example: “Enter vehicle information. Some fields may be prefilled.”

Use field group instructions to provide additional details specific to completing a field group within a form.

  • Example: “Download and complete the vehicle document below, then upload the completed file.”

Use helper text to help users understand how to complete an input.

  • Example: “Select two options”.

Use additional information to provide why information is needed or where to find information.

  • Example: “The account number is located at the bottom left of the billing statement.“

Do not use placeholders as they create both usability and accessibility issues.

Error messages

First, describe how to resolve the error. If needed, then describe what the error is or how it occurred. Additionally, avoid blame.

  • Poor label: “The password you entered is too long.”
  • Better label: “Enter 3–5 characters.”

Terms and conditions

Split terms and conditions into bullets or separate paragraphs to break up large blocks of text and make it easier to read. Avoid displaying the text as one large paragraph.

Table guidelines

Order columns in a table so that the most general and important information comes first, when possible.

  • Example: When listing available care providers in a table, you may display the following information in this order: provider name, specialty, location, phone number.

Date and time fields

Do not put the expected format for field data within the label of an input. The input itself should already provide a localized reference out-of-the-box as part of its helper text or validation messaging.

Metadata

Use bullet points to separate pieces of metadata in the UI and colons to separate labels from values in that list.

  • Correct: “File format: CSV • File size: 5KB”

Buttons

Buttons are labelled either with verbs or verbs then context. Choose verb only if the context is clear enough.

  • Poor label: “Work to submit”
  • Better label: “Submit”

Pega glossary

Reference the Pega glossary for a list of common Pega terms and definitions.

If you have questions, concerns, or any other feedback, please reach to us on Pega Support and include the capability ‘User Experience’ and ‘Constellation’ in your request.