Content

Overview

General best practices for writing content in and about BeyondTrust products. For copy guidance about a specific component or pattern, check the usage guidelines on each page.

Voice and Tone

Voice is how our writing sounds across an entire experience. It is part of our identity and never changes. Tone is the fluctuation of that voice that changes from one touchpoint of the experience to another.
You can think of our voice as our personality, and tone as our current mood. Just as our tone might change between a sales pitch and a support email, the tone we use onboarding users will differ from the tone that we use in error notifications. We might use a more relaxed and friendly tone for onboarding, and a more apologetic one for error messages. No matter what, our voice remains the same.

Voice Principles

BeyondTrust's brand voice, as determined by our marketing team, is bold, confident, supportive and genuine. How does this brand voice manifest in our writing?

Bold
We use strong, assertive language. We’re trustworthy and transparent.

Confident
We know what we’re talking about. We’re intelligent and informative, but never condescending.

Genuine
We’re authentic and sound like humans — not robots. We’re relatable, but not silly or irreverent.

Supportive
We’re approachable, while still empowering our users. We’re compassionate, yet still direct.

These principles are brought to life through our consistent choice of words, how many or little we use, and how we incorporate style elements like punctuation and capitalization.

How to talk to users

Don't use jargon or technical terms. Even if many of our users are experts, not all of them are. Plain language is best for everyone.

👍

Try this

That login information is incorrect.

❗️

Not this

Error 401. An authentication error occurred. Invalid credentials.

Use words that you would say naturally in conversation. Avoid internal lingo and choose simple words over complex ones.

👍

Try this

• We'll let you know when the discovery is complete. You can explore the dashboard or results while you wait.
• Cancel the scan.
• Computer

❗️

Not this

• You are free to navigate to other areas of the product. We will notify you when the discovery process is complete.
• About the scan
• Machine

Give simple explanations and instructions, without being verbose. Lead by telling users why they should do something.

👍

Try this

The system will be locked if not configured correctly. Double-check your information.

❗️

Not this

Any invalid configuration can render the system inaccessible. Please confirm the values that you have entered in the fields below.

Be succinct and focus on the need-to-know information. Aim to assure and educate, not patronize. Our users should feel knowledgeable and confident.

👍

Try this

You can create more resource zones and brokers later.

Roaming or cross-platform authenticators, like Yubikeys, are external security keys. Platform authenticators, such as Windows Hello or macOS Touch ID, are integrated and tied to a specific device. Both types of authenticators are FIDO2 certified and use biometrics instead of a password to log in.

❗️

Not this

Don't worry, you can create more resource zones and brokers later.

Roaming authenticators, also known as cross-platform authenticators, are external, FIDO2-certified security keys, such as YubiKeys, that perform user verification using biometrics. They can be used instead of your password when logging into the BeyondInsight Console on any machine and supported operating system that allows the use of external FIDO2 authenticators. Platform authenticators are integrated, FIDO2-certified biometric authenticators, such as Windows Hello or macOS Touch ID. These authenticators are tied to the machine where you registered the authenticator. They can be used instead of your password when logging into the BeyondInsight Console.

Concision is important, but so is clarity. Use enough words to not sound curt, but don't hide behind lengthy sentences.

👍

Try this

Policies at the top are the highest priority.

❗️

Not this

Policies on this computer are displayed in order of precedence, from the most important at the top to the least important at the bottom.

or

Policies ranked by importance.

Be mindful of rambling or redundancy.

👍

Try this

• Enter the email addresses of the users you'd like to invite.
  You created the rule.
• You created a rule.

❗️

Not this

• Enter the email address or addresses of the users you would like to invite as users.
• Success! You successfully created the rule.

Do use second person, as if you're speaking directly to the user.

👍

Try this

Go to your settings to update passwords.

❗️

Not this

Go to user settings to update passwords.

Acknowledge users’ effort and time, but don’t focus on being overly polite. Saying “please” every time action is required is unnatural. “Please” works best when we’re asking the user to do something truly inconvenient.

👍

Try this

• Thanks for filling out the form
• Select messaging options
• Please contact us

❗️

Not this

• Please fill out the form
• Please select from options to the left
• Please log in

Tone at different touch points

As mentioned, our tone changes throughout products. There are opportunities to use humor to make users smile, but often we should just get to the point. No matter what, we should be helpful and friendly.
We want users reading our copy to feel like there is a human guiding them through a product. We don't want to sound robotic or too technical, but we also don't want to sound too casual—like we aren't taking security seriously. Striking the right balance between a relaxed and formal tone can be difficult. Here are some examples of “getting it right”:

404

Too casual: Oops! Nothing found.

Too formal: 404. We apologize for the inconvenience. If you believe this is an error, contact support.

Just right: Page not found. It was either moved, removed, or never existed. Sorry for the interruption, we'll let you get back to saving the world.

Empty State

Empty state messages should present an opportunity to a user by showing what the space can do for them. They shouldn't be robotic, but they shouldn't be too casual either.

Too casual: It's looking lonely in here! What should we connect first?

Too formal: No connectors added.

Just right: Start connecting to your other security platforms to get all your identity data in one place.

No results

No results messages for search should clearly tell users nothing was found and offer suggestions about what they can try instead to find results. If there are filters applied, let the user know they need to edit them. They shouldn't be too technical, but be specific about the type of data they're trying to access.

Too casual: Hmm, nothing to see here!

Too formal: Your query produced no results. Enter new values.

Just right: No rules matched your search. Try searching by another keyword.

Welcome

Welcome messages are a chance to build excitement and briefly introduce what a product can do for a user, as well as direct them to resources.

Header: Welcome!

Description: You can now start rolling out and managing your privilege management solution. Select the help icon at any time to get guides, documentation, and support.

Button: Let's go

"What's new"

"What's new" messages should focus on what the user benefits from the changes. There's no need to get too technical, but you can direct the user to more information.

Header: We've made some improvements

Description: The new Privilege Management for Windows and Mac includes features and enhancements that make it easier to understand behavior data. Plus, seamlessly refine your policies, onboard endpoints, and access your license key information.

Check out the What's New section of the Knowledge Center or read the release notes.

Button: Got it

Grammar and spelling

While content is often localized, use American English for consistency.

👍

Try this

• Organized
• Behavior
• Adapter

❗️

Not this

• Organised
• Behaviour
• Adaptor

Use simple contractions to sound natural. Avoid less common ones.

👍

Try this

• You're responsible for storing the Client Secret in a secure location. This is the only time you'll be able to view the Client Secret.
• Must not.
• That will.

❗️

Not This

• You are responsible for storing the Client Secret in a secure location. This is the only time you will be able to view the Client Secret.
• Mustn't.
• That'll.

When there is a possibility for more than one item, don’t use a (s) in parentheses or a slash with the plural form. Choose the plural, even if the user might only select one thing.

👍

Try this

• Updates
• Reboots
• Policies

❗️

Not this

• Update(s)
• Reboot(s)
• Policy/ies

Sentence structure

Start with “If” so that users can skip over the content if it doesn't apply to them.

👍

Try this

If you want to include the new update, delete the existing schedule and create a new one.

❗️

Not this

Delete the existing schedule and create a new one if you want to include the new update.

Think about using the active voice instead of the passive voice. The active voice is when the subject is the main focus of the sentence, not the object or action.

👍

Try this

Scan times are in your local time zone.

❗️

Not this

Scan times are localized to the scanner time zone.

Use complete sentences but keep them simple and succinct.

👍

Try this

Go to Profile and select Settings.

❗️

Not this

Go to Profile. Select Settings.

Punctuation

Avoid asterisks. When information is hidden in the fine print, it reduces trust.

👍

Try this

• Add up to 3 users.

❗️

Not this

• Add users*

*You can only add 3 users.

Use periods to end complete sentences. Don't use periods in headings or labels. In bulleted or numbered lists, use periods when the list item is a full sentence, not a single word or short phrase.

👍

Try this

What does Insights offer?

• Gives unparalleled visibility into your identities, accounts, and privileged access.
• Detects suspicious activity from high-risk privileged accounts.
• Proactively recommends actions to reduce your attack surface.

❗️

Not this

What does Insights offer?

• Identity and account visibility.
• Detections.
• Recommendations.

Exclamation marks are often overused. Limit 1-2 per screen or better yet, save them for truly exciting parts of the experience.

👍

Try this

• Welcome!

❗️

Not this

• Discovery is now in progress!

You can use quotation marks to indicate the name of an item. When referring to section titles on a UI, use bold instead of quotation marks. Punctuation should nearly always go inside the quotation.

👍

Try this

• You created the group "Halifax Office."

❗️

Not this

• To delete, select "Delete group".

Do use commas in sentences, not lists.

Use serial commas, also known as an Oxford comma, after the “and” in sentences that list 3 or more items. While it can be tempting to drop the serial comma to save space, it can also make things more confusing by not separating the last items in a list.

Without the serial comma in the first example, it's not clear that recommendations and detections are two different things.

👍

Try this

• Use Insights to view entitlements, recommendations, and detections.
• Configure other details such as screen resolution, session node, smart sizing, and more.

❗️

Not this

• Use Insights to view entitlements, recommendations and detections.
• Configure other details such as screen resolution, session node, smart sizing and more.

Use em dashes (the long ones) for emphasis and en dashes (the short ones) to specify a range. Don't use spaces for en dashes. You can use spaces for em dashes if there is enough room.

👍

Try this

5-10 administrators

❗️

Not this

5—10 administrators

Use colons, not semicolons, to introduce bulleted lists or as part of a definition. The rules around semicolons in sentences can be hard to remember. When in doubt, just use a period or comma instead.

👍

Try this

Configure details:

• Screen resolution
• Session node
• Smart sizing

❗️

Not this

Configure details;

• Screen resolution,
• Session node,
• Smart sizing,

Avoid ampersands, write “and” instead. Ampersands draw attention to the least important part of the text and should only be used for titles. Similarly, choose "or" or "and" instead of using a "/".

👍

Try this

• Enter details for known systems and accounts
• Systems and Accounts
• Active and completed scans

❗️

Not this

• Enter details for known systems & accounts
• Active/completed scans

Capitalization

Only capitalize proper nouns.

👍

Try this

• Password Safe lets users configure Smart Rule filters.
• Insights lets users manage tenants in their organization.

❗️

Not this

• Password Safe lets users configure smart rule filters.
• Insights lets users manage Tenants in their Organization.

Don't use all caps in the middle of a sentence for emphasis, or as labels for buttons.

👍

Try this

• If all of the conditions are met.
• Try Insights for free.

❗️

Not this

• If ALL of the conditions are met.
• Try Insights for FREE.

Title case is when you capitalize the first letter of most words, sentence case is when you only capitalize the first letter of the first word.

• This is an Example of Title Case
• This is an example of sentence case.

Sentence case is highly favoured by tech companies as it is more readable, easier to localize, and has less rules to remember. For these reasons, we should move towards sentence case everywhere.

👍

Try this

• Leader in intelligent identity and access security
• Dangerously outdated browser used

❗️

Not this

• Leader In Intelligent Identity And Access Security
• Dangerously Outdated Browser Used

Formatting

Do nearly always use numerals. Don't use superscript for ordinal numbers.

👍

Try this

• You can view up to 10,000 events.
• Third party

❗️

Not this

• You can view up to ten thousand events.
• 3rd party

Do use bulleted lists and numbered lists to make content more scannable. Use numbers for sequential lists. Don't include blocks of text that are more than 3-4 lines long or 50 characters wide.

👍

Try this

1. Enter 3 or more characters to search for the user's first name, last name or description.
2. Check the box to assign the user to the selected group.

❗️

Not this

• Please enter three or more characters to begin searching against user's first name, last name or description. If a user is already assigned to all of the currently selected groups, their result will display as checked. If the user is not assigned to one or more of the currently selected groups, their result will display as unchecked. Check the box to assign that user to all currently selected groups.

When giving instructions, do use bold type to refer to titles or labels on a UI, not quotation marks. You can also use bold for emphasis.

👍

Try this

• Select Create Rule under Management Rules.

❗️

Not this

• Select “Create Rule” under “Management Rules”

Word choice

Avoid using and/or. And/or is a legalise term that often leads to confusion and ambiguity. Instead, pick one or the other, or replace with “x or y, or both.”

👍

Try this

• Choose a user or a group, or both.

❗️

Not this

• Choose a user and/or group

Avoid adverbs when writing instructions. While there are times to use descriptive words to talk about our products, we don’t want to make assumptions about the user’s level of understanding or how the process is going for them.

👍

Try this

• Add known systems
• Create the system

❗️

Not this

• Quickly and easily add known systems
• Simply create the system

If space is limited, consider cutting words and articles (the, an, a).

👍

Try this

• Start scan
• Copy details

❗️

Not this

• Start a scan
• Copy the details

Calls to action (CTAs)

Interfaces with actions like creating, editing, or deleting should have a title that clearly states the action and the name of the item. Be specific. There’s usually no need to include the word “new” — it’s implied, since anything created is new.

👍

Try this

• Create GitHub Connector

❗️

Not this

• Create New Connector

Editing actions should indicate what's being edited. The label should be Edit ___. For inline editing, the field name should be specified. If the action opens a panel, then the title of the panel should also include what is being edited. The confirmation button should be Save Changes.

👍

Try this

• Title or label: Edit message name
• Button: Save changes

❗️

Not this

• Title or label: Edit property
• Button: Confirm

The title should match or mirror the button. Some items with subcategories of data might have advanced views with several titles. In this case, the title might differ — as long as the main title contains the item name.

👍

Try this

• Title: Add IP addresses to allow list Button: Add addresses

❗️

Not this

• Title: Add IP addresses to allow list Button: Update list

Do use strong verbs to encourage action. Generally, put the verb first.

👍

Try this

• Assign policy to groups
• Edit policy

❗️

Not this

• Groups: Assign policy
• Policies: Edit

If no action can be taken and a user is just viewing an existing item, the title can just be the name of the item.

👍

Try this

• Activity History

❗️

Not this

• View Activity History

Links and labels

Clearly describe where links will take a user. Links that just say "Learn more" are known as “lazy links” — they're inaccessible, ambiguous, and create uncertainty. Use descriptive and detailed links instead.

👍

Try this

• Need help? Read our FAQ or contact support.

❗️

Not this

• Need help? Click here.

When an item has a long name, like a file, always use the type of item.

👍

Try this

• Edit Exclusion

❗️

Not this

• Edit C:\Windows\System32\app.exe

Accessibility and inclusion

Don't use black to refer to something negative and white to something positive.

👍

Try this

• Ethical hacker
• Block list
• Allow list

❗️

Not this

• White hat hacker
• Black list
• White list

Do use gender neutral language.

👍

Try this

• They/them/theirs

❗️

Not this

• She/her/hers
• He/him/his

When we use disable to describe a feature that is turned off or not functioning, we reinforce the idea that being disabled is lesser or negative.

Since disabled is an HTML attribute it can be appropriate in the context of development and in internal documentation. There are also non-BeyondTrust applications and systems that use disable that we may have to reference. While the term disabled has previously been an industry standard, the industry is changing and we want to be part of that change.

Always consider an alternative when writing user-facing content.

👍

Try this

• Activate or On
• Deactivate or Off

❗️

Not this

• Enable
• Disabled

Write simply to accommodate lower reading comprehension.

👍

Try this

• You'll get this notification if a performance indicator exceeds one of your set thresholds for a long period of time. For example, CPU going below 80%.

❗️

Not this

• You will receive this notification if a performance indicator you have configured exceeds one of the thresholds you have set (for example, CPU passing 80% as a medium alert). These alerts will be sent when the performance indicator drops below 80% for a sustained period.

Acronyms don't localize well and aren't always screen reader friendly. They also often take more cognitive effort to deciper and remember. If you need to use an acronym, always spell it out first and use the acronym in brackets.

👍

Try this

• Start a Remote Desktop Protocol (RDP) session.

❗️

Not this

• Start a RDP session.

Don't use verbs like “click” or “tap”—not all users can physically interact with a mouse or screen.

👍

Try this

• Select create directory credential.

❗️

Not this

• Click create directory credential.

Do think carefully about the idioms you use. Many idioms have harmful connotations.

👍

Try this

• Legacy

❗️

Not this

• Grandfathered in

Related

Referenced in this section:

Button component

Filter pattern

Text link component