Voice and Tone
Deliver clear, consistent experiences to HPE customers by following guidelines for the voice and tone of text-based user interface elements.
The HPE Design System crafts words into content that cultivates an exceptional user experience.
The user experience is built upon our content. Every word we write is a carefully-considered concept that voices our values:
- Open: We foster inclusive experiences that are personal, accessible, and transparent.
- Courageous: We empower users with decisive and experienced guidance.
- Inspired: We share our drive of 'yes we can' with users.
We exercise empathy in our voice through situational tones that speak to each context, audience, and subject matter. We can be a force for good by creating content that is:
- Active
- Positive
- Objective
- Fact-based
- Plain English
Refer to the guidance for HPE's Voice for more information.
Best practices
The following are some high-level guidelines for constructing good messaging.
Writing effective content
A design speaks for itself.
It communicates the interaction of the user experience; how a task is accomplished.
Content supplements design.
It communicates the goal of the user experience; why a task should be accomplished.
We can create meaningful user experiences by writing clarity into our content; what we say and how we say it. Clarity simplifies complex ideas and connects one idea to the next to bridge the gap between user and application, task and goal.
We can write clear content with a few simple qualities:
Approachable
Write with clear language to communicate clear ideas.
Write to users in plain language, grounded in positive ability and action. Plain language requires less cognitive effort from users, improving time to action. Write at a United States grade 7 reading level to create straightforward, succinct, and consistent content.
Use the Hemingway App to check the readability of content.
Identify and communicate key points by separating and refining ideas to their essence. Words can often be reordered and refined to create simple and neat sentences.
Read your message aloud to hear if it sounds like natural conversation. Content that sounds natural is easier to read and understand.
Objective
Anchor content in fact and objectivity, free of bias and judgement.
Content based in fact fosters clarity and reliability. Content based in opinion introduces ambiguity.
Consider the connotations of content. Words like Error can unintentionally imply that the user is at fault and convey judgement of their actions.
Consider content from the user's perspective and goals, not what the UI can do.
Format
Write content that complements its element in the user interface.
Elements like headers and interactive objects require concise language that communicates a single point.
Body content provides room to elaborate but should still be succinct.
Position
Establish context with language that positions the user in the application: where they are and where they are going.
Conversational language in macro settings, such as a dashboard that provides a broad set of interactions, can communicate big-picture goals.
Definitive, action-oriented language in micro settings, such as a step in a workflow, can communicate the immediate task.
Flow
Write clear paths to goals and resolutions.
Organize content so that one idea flows into the next and builds upon itself, enabling users to quickly make informed decisions.
Conversational American English
Variations of English are used throughout the world. However, to maintain consistency in HPE's voice, the messaging standard is to use conversational American English.
Below are common usage and spelling differences between American, Indian, and British English and suggested resolutions for where differences arise.
British English
When there is a difference between American and British spelling, use the American spelling.
Many British words are spelled ending in "our" such as "colour". Use the American "or" variant instead: color.
Many British words are spelled ending in "yse" (analyse) or "ise" (realise). Use the American "yze"/"ize" variants instead: analyze/realize.
Additional common differences:
British | American |
---|---|
Licence | License |
Cancelled | Canceled |
Centre | Center |
Catalogue | Catalog |
Behaviour | Behavior |
Favourite | Favorite |
Grey | Gray |
Chips | Fries 😊 |
Biscuit | Cookie 😊 |
When using a spelling/grammar checker, set your locale to provide American English suggestions.
Indian English
This is a collection of common words or phrases used in India, that are not used in American English:
If you find yourself using this… | Example | Use this instead | Why? |
---|---|---|---|
Sorted | The feature is not sorted. | Use either "elaborated", "thought through", "analyzed", "planned". | Confusing. "Sorted" implies sorting in the computer sense. |
Thus / Hence | …, thus you must factory reset. | Use "therefore". | Uncommon or too formal. |
Do the needful | The server is down. Do the needful. | This is similar to "do what is necessary" or "do whatever it takes", but neither should be used in our messaging. Instead, be specific about what the user should do. | Never used. We should always be specific. |
We will revert back | I send an email saying "do it like this" and you reply, Thanks, we will revert back. | We will get back to you. | "Revert back" implies going back to a previous revision. |
Strong all the more | makes the case strong all the more. | makes the case stronger. | Never used. |
I have a doubt | I have a doubt about that. | I have a question | "I have a doubt about that" implies you think it is incorrect. |
Point of view
Point of view is the perspective from which the message is written. First person perspective uses words like: I, me, us, we, our, etc. Second person uses any form of the word "you" which has the effect of addressing the reader. Third person directs the reader to things that are neither the writer or the reader.
Examples:
- We noticed the server is malfunctioning. (1st person-ish)
- Your server is malfunctioning. (2nd person-ish)
- The server is malfunctioning. (3rd person - no focus on the writer or the reader)
Referring to support
- Do not tell the user to contact their administrator. The user is likely the administrator.
- Do not tell the user to contact HPE. A 3rd party may be providing support to the user.
- Use something like: Contact your authorized support representative.
- Do not overuse this phrase. If the resolution to a problem is clear, just give the resolution and do not add that the user should contact support.
- Contacting support costs everyone time and money, so do not turn every issue into a potential support issue. It makes our product seem unnecessarily fragile and can result in unnecessary support calls.
- Do use this phrase for internal errors where there's nothing else the user can do (i.e. when it is the only resolution).
Scale
Consider singular and plural use cases and craft messages for each.
If a sentence contains a list, do not allow the length of the list to be unbounded. Instead, consider an approach where three items are shown and the remaining items are grouped: The following policies have not been implemented: Policy A, Policy B, Policy C, and 5 others.
Quoting
In messaging that contains user-specified content, use double-quotes around this content if it is not rendered as a hyperlink. If user-content is rendered as a hyperlink, the hyperlink styling is sufficient to offset the content from other text in the message.
Why is this important? User-entered names can contain spaces, and if they are not quoted or rendered as hyperlinks, they can hinder comprehension of a message.
Here is a correct example: the uplink set "{0}" has a problem. Compare this to an incorrect example: the uplink set {0} has a problem. If the uplink set is named "deleted", this will read as the uplink set deleted has a problem.
Guidelines
These concrete rules structure our communications.
Capitalization
There are five types of capitalization.
- Sentence case, where the first letter is capitalized and subsequent words begin with lowercase letters, with some exceptions, such as proper nouns. (example: Storage volume)
- Title case, where most words are capitalized except for "connector" words such as "the," "an," "or," etc. (example: "The Benefits of Cloud Storage Explained")
- PascalCase, where there are capital letters inside the word, almost always for branding purposes. (example: GreenLake)
- All lowercase, where every single word is lowercase (example: "lowercase exudes an approachable and casual vibe")
- All caps, where every letter is capitalized (example: ALL LETTERS ARE CAPITALIZED)
At HPE, almost all text should be written in sentence case. Never begin a sentence or phrase with a lowercase letter because it is too casual for our brand. Do not write in all caps because it is equated with yelling and increases stress.
Sentence case should be applied on:
- Attribute labels
- Column headings
- Legends
- Tabs
- Menus
- Paragraphs of text
- Tips
- Notifications
- Help
- Dialog titles
- Section and subsections/subheadings
- Buttons, except for those ending in the following short prepositions: at, by, for, in, of, off, on, out, to, up
- Correct: Sign Up
- Incorrect: Sign up
Title case should only be applied on:
- Page titles
Capitalize proper nouns. HPE brand and product names are proper nouns.
Fight the urge to elevate normal nouns to proper noun status. For example, if you are in a "data sources" page and need to say something about data sources, do not capitalize it. Unless it is a true proper noun, leave it uncapitalized when following sentence capitalization rules.
When writing instructions, you can choose to refer generally to the action that should be taken or to the button or page. When you refer generally to an action, use lowercase. When you refer to a specific button, page or other element, follow the case of the element.
Example of when you can refer to action in a general manner: To create a data fabric you must first [anchor]create a new cluster[anchor].
vs.
Example when you refer to a page or button: First, go to the "[anchor]Create a New Cluster[anchor]" page to create a data fabric.
Acronyms and initialisms
Acronyms and initialisms can be problematic and should be used with care. Because they are shortcuts communicating a concept in a visually shortened form, they tend to become distinct languages for a limited set of "insiders." However, for those who are less fluent or use the language infrequently, acronyms and initialisms are actually detrimental. Acronyms increase the cognitive load on the user, forcing them to "decode" the message before comprehension, and tend to be exclusionary rather than inclusive. If an acronym or initialism is needed, define it the first time it is used. Additionally, only use the acronym if it is used multiple times in the message.
- Incorrect: The UBC is meeting tomorrow.
- Incorrect: The UBC (University Building Council) is meeting tomorrow.
- Incorrect: The University Building Council (UBC) is meeting tomorrow.
- Correct: The University Building Council (UBC) is meeting tomorrow. If you have UBC-related business, send it to the UBC administrator for addition to the meeting agenda.
Branding
To aid in comprehension, do not use full brand/product names in messaging. Refer to these with shortened names. For example, "HPE GreenLake Lighthouse" is a mouthful and if needed several times in a sentence, set context and consider using a simpler "Lighthouse" the second, third, Nth time.
Language dos and don'ts
Do this:
- Use words like "a", "an", "the" so we don't sound like a robot.
- Add punctuation to the end of each sentence.
- Use correct punctuation within a sentence.
- Use contractions to emphasize a conversational tone.
- For example, 'you are' can be shortened to 'you're', 'we will' can be shortened to 'we'll', and 'is not' can be shortened to 'isn't'.
- Adjectives typically come before nouns.
- Incorrect: the operation specified is…
- Correct: the specified operation is…
- Adjectives in English appear in a specific order. If this order is violated, the sentence will seem odd.
- From the book The Elements of Eloquence: ...adjectives in English absolutely have to be in this order: opinion-size-age-shape-color-origin-material-purpose Noun. So you can have a lovely little old rectangular green French silver whittling knife. But if you mess with that word order in the slightest you’ll sound like a maniac. It’s an odd thing that every English speaker uses that list, but almost none of us could write it out.
- There's a slightly different order listed in the Cambridge Dictionary.
- Therefore: two failing SATA SSD drives and not SSD SATA failing two drives
Don't do this:
- Avoid possessives (e.g. the server hardware's power is off).
- Eliminate run-on sentences.
- Don't overuse the word "please". While "please" is allowed, starting every action phrase with the word "please" is not appropriate. In general, we should be limiting the use of "please".
- When the subject of a sentence is a specific resource, do not use that resource’s name as an adjective describing a resource type. Instead, use the type as an adjective describing the resource:
- Incorrect: the ABC uplink set has…
- Correct: the uplink set "ABC" has…
- It is not necessary to tell the user to retry the operation in most cases. For example, if the user has entered incorrect or illegal values, we only need to tell them to specify correct values and do not also need to tell them to retry the operation. The retry is intuitive and obvious in these cases.
- Never tell the user to retry after some time. Be more specific.
- E.g. "after 3 minutes" or "after the refresh has completed."
- Don't tell the user to try or attempt things. It does not convey confidence. Instead, tell them to do things.
- Incorrect: Try resetting the interconnect.
- Correct: Reset the interconnect.
- Don't say bad request. This is blaming the user. Just explain what is wrong.
- Do not use internal terminology in external messaging.
- Do not refer to "the" or "your" administrator in messaging. More often than not, the user reading the message is the administrator. Be more specific.
- When making parenthetical comments…
- Don’t add spaces inside the parentheses: this is bad ( yes it is ).
- Do add spaces outside the parentheses: this is bad(yes it is). The exception would be things like “server(s)”.
- Avoid incorrect use of the word "input".
- Incorrect: Specify a valid certificate as input.
- Correct: Specify a valid certificate.
- Incorrect: One of the input parameters is null.
- Correct: One of the parameters is null. or One of the specified parameters is null. or The "name" parameter is null.
Other common problems and how to address them
The following are commonly misspelled/mis-capitalized terms:
- The following must be spelled/capitalized as shown:
- Kubernetes
- Ethernet
- Fibre Channel
- FCoE
- SNMP, SNMPv3
- ID (not id or Id)
- OK (not ok, Ok, or okay)
- I/O (not IO or i/o)
- API (not xApi) (either that, or be explicit and say X-API-Version)
- "Log in" is a verb (e.g. "Log in to the server").
- "Login" is a noun or adjective (e.g. "The login token has expired").
- Use the word "and" instead of an ampersand "&".
- Filesystem is one word.
- Use "host name" when referring to the name of a host.
- Use "hostname" when referring to the Unix command.
The following table contains a set of common mistakes found in messaging, along with suggested corrections:
Don't | Do | Notes | |
---|---|---|---|
app | application | ||
internal error | unexpected problem | ||
coding error | unexpected problem | ||
issue/error | problem | ||
Failed to | Unable to | ||
X failed | Unable to X | ||
since | because | Unless referring to time | |
there's | there is | ||
non something | non-something | ||
can not | cannot | ||
associated to | associated with | ||
as the | because the | Only when it can be substituted with "because the". There are valid uses of "as the", e.g. X must be the same as the Y. In general, don't use "as" where you can use "because". | |
as it has | because it has | In general, do not use "as" where you can use "because" | |
make sure | ensure | ||
check if | ensure that | Note: "check if" or "verify that" are never valid resolutions because they don't tell you what to do or how to do it. A resolution must be actionable. For example: "Check if the required CA certificates have been added and are valid" is not a good resolution. It does not tell you what to do if the certs have not been added or if the certs have been added but are not valid. Our messaging must lead the user to success — not leave them guessing. | |
provide / provided, supply / supplied, give / given | specify / specified | Be careful with blind replacements here. In many cases, it is possible, but our "contact support" message includes the word "provide" and must not be changed to say "...specify a support dump." | |
try again / retry operation (when used as the sole recommended action) | Tell the user what they need to change and then tell them to try again. | At minimum, each instance needs to be evaluated more deeply to see what our code could do to prevent the user from doing something we could do ourselves. If a retry is due to a timeout (proxy, etc), then first see if the code can be changed to use an exponential backoff algorithm to do its own retries. Any time that retry will be used in messaging, the message itself needs more explanation for what actually went wrong. | |
try again / retry operation (without understanding the larger context) | Understand the context and give the correct recommendation. | E.g. in a sub-task of "add enclosure", a try again resolution of any kind is inappropriate because the add enclosure will always result in an enclosure resource being created. The user cannot try the enclosure add a second time. | |
should | must | "Should" does not mean "must". If you say that a value should be 0, that is only a suggestion. If it is a requirement, use the word "must". | |
has to be | must be | ||
were / was / had | are / is / has | Use "were"/"was"/"had" to refer to the past and "are"/"is"/"has" to refer to the present. Notifications must typically refer to the present. Wrong: "there were no licenses". Right: "there are no licenses". Acceptable: "Multiple occurrences of the same network were found…" | |
mark | set / specify | Wrong: "There is more than one setting marked as Required". Better: "More than one setting is specified as required."" | |
you / your | TBD | We strive to not use personal pronouns in error messaging. It is too easy to blame the user by using personal pronouns. In general, if the sentence can easily be changed to eliminate the use of these pronouns, do so. | |
as per the | per the | ||
hit / hitting | press / pressing | Users do not hit the keyboard. They press keys. | |
power down / turn off | power off | Also consider whether a shutdown is required. | |
ongoing | in progress | When referring to tasks, "ongoing" has the wrong connotation: long running perpetual tasks. This is OK: "ongoing server management". Otherwise, use statements like: "the software upgrade is in progress" | |
recreate | re-create | "Recreate" means to enjoy a leisurely activity. Re-create means to create again. Try to avoid using recreate/re-create, in general, and see if there is a way to rephrase the message without this term. | |
getting | retrieving | ||
updation | update | "updation" is not a word. | |
is belonging | belongs | Bad example: "Server profile assigned to the hypervisor profile is belonging to enclosure group…" | |
is having | has | Bad example: "Server profile assigned to the host is having a different server hardware type…" | |
is not having | does not have | Bad example: "Hypervisor host XYZ is not having a server profile attached to it and so it is unsupported." | |
is matching | matches | ||
is not matching with | does not match | ||
there are not enough | there are insufficient | In general, try to avoid this entirely. It is odd to start with "there are" only to end with the fact that this isn't true. For example, instead of telling the user that there are insufficient licenses to perform an action, you might tell them that all licenses are in use and the action cannot be performed. | |
simply | Don't use this word. Never presume something is simple for the user. | ||
drop down | menu / selection list | Refer to either a menu (e.g. action menu) or a selection list. | |
screen | page / dialog | A page is commonly a linkable, top-level visualization page shown in a browser. A dialog is a pop-up (sidebar, central, full-page) that overlays a page and typically results from the user performing an action. | |
verify if / check if | Don't do it. Example: "Please verify if the input is bad." Are we asking them to ensure it is bad or are we asking them to ensure it is good? | ||
invalid | not valid | Machine translation can incorrectly translate "invalid", so it is better to use "not valid". However, it is even better to use neither and instead be specific about what the problem is. For example, if an input is not valid because it is too long, then tell the user the input is too long instead of telling them it is not valid. See: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/i/invalid-not-valid | |
and if | Split into two sentences | Bad example: "Retry the operation and if the problem persists, contact your authorized support representative and provide a support dump". Good example: "Retry the operation. If the problem persists, contact your authorized support representative and provide a support dump". In general, each separate option in an error resolution should be either, its own sentence, or in a comma separated list. The last-resort action of contacting support must always be in its own sentence. | |
re-order | reorder | Use this to describe the action of reorganizing items in a list, rather than re-order (placing another order). |
Implementation
Implement effective communications with these conventions.
Documenting messages
A best practice for developers is to add comments to messages in the properties files or message catalogs. Reviewers and translators (and ultimately, users) will thank you.
- Document all parameter substitution values. When the value is a resource, be specific. Is it a name? Is it a URI? Is it raw JSON that needs to be encapsulated in curly braces? Or is it pre-formatted JSON that includes curly braces?
- For errors and alerts, document the severity associated with the message.
- Document the type of message (alert, task, etc).
- If a message to users doesn't state how its associated problem occurrs or what to do about it, document those details.
- Add context for the task being performed or the resource category involved.
- Document if and when API-only messages don't display in the UI.
To localize content for international audiences, reference our internationalization resources.
User input
Unless there is a compelling reason, do not limit the character set that a user can use to name things. Names commonly contain non-alphanumeric characters and we must handle them correctly on input and in re-display via messaging. For example:
- Joe’s system (apostrophe for a possessive)
- O’Reilly Auto Parts (apostrophe in name)
- Yahoo! Client (company name includes a symbol)
- Frank James-Martin (Hyphen in name)
- DC-NY-East (Dashes in internal company identifiers)
- Björk Guðmundsdóttir (Unicode characters)
- 联想 (Unicode characters)
- John Q. Public (punctuation for abbreviation)
- “”> (An actual company name in the UK that the UK Companies House had to ban because it broke their systems. See article.)
Proper encoding/decoding of user-entered input must be performed to prevent SQL/XSS attacks. Input such as the following user input must not cause problems when the user-generated input is later incorporated in application messaging:
- Robert’); DROP TABLE Students;-- (see: https://xkcd.com/327/)
User-generated input can be arbitrarily long. When confronted with displaying user-generated input, plan for the 80% case, but define which of truncation (with hover) or wrapping will be used.
Maintainability
A best practice for developers is to use parameter substitution in messaging where branded names occur.
A product's branding is likely to evolve over time. For example, GreenLake Central
recently rebranded as Cloud Services. Imagine the multitude of instances to which
the product name was referred. Use of parameter substitution limits the number changes to
be made while ensuring brand names are spelled and capitalized consistently in all
messages. Implementing messages with a parameterized ${prodname}
instead of
hardcoded messages allows for a product's branding to be changed easily,
confidently, and comprehensively.
Lastly, consider formal and informal substitution values which can be used in
various contexts. For example:
- formal = HPE Ezmeral Container Platform
- normal = Ezmeral Container Platform
- short = Container Platform
Case study
Consider a case with messaging related to a condition where a Kubernetes cluster is running low on available memory. Versions 1-7 highlight bad practices and identify the respective problems within each version. Lastly, a best practice example is provided.
Version 1
Problems:
- No punctuation
- No verb
- No context (what cluster?)
- Robotic (robots don't use words like "a", "the", "is")
- Incorrect capitalization of memory (it is not a proper noun)
Version 2
Problems:
- It is better to have the resource type (cluster) precede the resource name (ABC).
- Names are user-specified and can cause readability issues if not quoted or hyperlinks. See what happens if "ABC" is replaced with names like "the", "storage", "Joe's", "obsolete", or any random string containing spaces.
- What does "out of memory" actually mean? We should be more specific.
Version 3
Problems:
- Strongly consider hyperlinking any named resource so that a user can directly navigate to it from a notification.
- 95% of 10TB means that 500GB are still free. But, 95% of 16GB means only 800MB remain. Showing only percentages doesn't offer the user enough context to make a decision.
Version 4
Problems:
- What is the user supposed to do about this? Never raise an issue without offering a solution.
Version 5
Problems:
- What is the needful? This is a saying not used in conversational American English and does not give the user specific guidance.
Version 6
Problems:
- The user purchased the cluster to use it. Telling them to stop using it is not going to go over well.
- Is this really a critical issue? Unused resources are often considered wasted resources. It is actually a good thing to be fully utilizing your hardware.
- In an aaS world, additional capacity should be a simple add-on to an existing service. As such, this may not be a critical issue, but could be transformed to a lower priority marketing message.
Version 7
Problems:
- If possible, give the user a way to directly perform a mentioned action.
Best practice
- Correct capitalization and punctuation is used.
- The named resource is hyperlinked so that a user can directly navigation to it from a notification.
- A solution to the issue is provided to the user.
- Context on how much available memory is provided.
- The user is given a way to directly perform a mentioned action.
Still have questions?
Something missing or looking for more information? Get in touch to help make the HPE Design System better.