Voice and Tone

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.

The following are some high-level guidelines for constructing good messaging.

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:

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.

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.

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.

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.

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.

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.

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:

When using a spelling/grammar checker, set your locale to provide American English suggestions.

This is a collection of common words or phrases used in India, that are not used in American English:

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)

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

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.

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.

These concrete rules structure our communications.

There are five types of capitalization.

1. 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)
2. Title case, where most words are capitalized except for "connector" words such as "the," "an," "or," etc. (example: "The Benefits of Cloud Storage Explained")
3. PascalCase, where there are capital letters inside the word, almost always for branding purposes. (example: GreenLake)
4. All lowercase, where every single word is lowercase (example: "lowercase exudes an approachable and casual vibe")
5. 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 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.

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.

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.

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:

Implement effective communications with these conventions.

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.

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.

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

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.

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)

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.

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.

Problems:

• What is the user supposed to do about this? Never raise an issue without offering a solution.

Problems:

• What is the needful? This is a saying not used in conversational American English and does not give the user specific guidance.

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.

Problems:

• If possible, give the user a way to directly perform a mentioned action.

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