hpe-branding/04-voice-and-tone.md

# 04 — Voice and tone for UI strings

Scope note: these are HPE's rules for **text inside a product UI**: labels,
buttons, error messages, notifications, help text, empty states. They are not
the rules for prose in this repo. See the note at the end.

The source page (`foundation/voice-and-tone`) is by far the largest doc on the
site at roughly 55 KB, which is a signal in itself. HPE treats UI copy as a
design surface, not an afterthought.

## Capitalization

Five capitalization styles exist. HPE uses one of them for almost everything.

**Sentence case is the default.** First letter capitalized, everything else
lowercase except proper nouns. Applied to: attribute labels, column headings,
legends, tabs, menus, paragraphs, tips, notifications, help, page titles,
dialog titles, section and subsection headings, and buttons.

Two hard prohibitions:

- **Never begin a sentence or phrase with a lowercase letter.** Too casual for
  the brand.
- **Never use all caps.** It reads as yelling and increases user stress.

**Title case is only for** the title of an event, program, or website, and for
proper nouns. HPE brand and product names are proper nouns.

### The button exception

Buttons take sentence case **except** those ending in one of these short
prepositions: `at, by, for, in, of, off, on, out, to, up`. Those get the
preposition capitalized.

```
Correct:   Sign Up
Incorrect: Sign up
```

This one is counterintuitive and easy to get wrong in review, so it is worth
quoting verbatim when it comes up.

### Do not promote common nouns

The docs are direct about this: "Fight the urge to elevate normal nouns to
proper noun status." On a "data sources" page, write *data sources*, not
*Data Sources*, unless it is genuinely a proper noun.

### Referring to UI elements

When you describe an action generally, use lowercase. When you name a specific
button or page, match that element's actual case.

- General action: "To create a data fabric you must first create a new cluster."
- Specific page: "First, go to the *Create a New Cluster* page to create a data
  fabric."

## Acronyms

The stated position is that acronyms are exclusionary. They create an insider
language and force everyone else to decode before they comprehend.

Two conditions, both required:

1. Define it on first use.
2. Only use the acronym at all if it appears **multiple times** in the message.

The worked example is unusually strict, so here it is in full:

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

The third one is incorrect because the acronym is introduced and then never
used again. Expanding it earns nothing.

## Product names

Do not use full brand and product names in running messages. Set context once,
then shorten. The docs' own example: *HPE GreenLake Lighthouse* is a mouthful,
so use *Lighthouse* on second and subsequent references.

## Point of view

Three options, with the effect of each spelled out:

- First person: "We noticed the server is malfunctioning."
- Second person: "Your server is malfunctioning."
- Third person: "The server is malfunctioning." (focus on neither writer nor
  reader)

The page presents these as choices rather than mandating one, so pick by
context and stay consistent within a flow.

## Do

- Use articles ("a", "an", "the") so the text does not read like a robot.
- Punctuate every sentence, correctly, including internally.
- **Use contractions.** "you're", "we'll", "isn't". This is explicitly
  encouraged for a conversational tone.
- Put adjectives before nouns: *the specified operation is*, not *the operation
  specified is*.
- Order multiple adjectives correctly: opinion, size, age, shape, color, origin,
  material, purpose, then noun. So *two failing SATA SSD drives*, never *SSD
  SATA failing two drives*.

## Do not

These are the rules that most often catch real error strings:

- **Do not blame the user.** Never say *bad request*. Explain what is wrong.
- **Do not hedge.** Never tell a user to *try* or *attempt* something; it does
  not convey confidence. Write *Reset the interconnect*, not *Try resetting the
  interconnect*.
- **Do not say "retry the operation"** in most cases. If the user entered an
  illegal value, telling them to supply a correct one is enough. The retry is
  obvious.
- **Never say "retry after some time."** Be specific: *after 3 minutes*, or
  *after the refresh has completed*.
- **Do not refer to "the" or "your" administrator.** The person reading the
  message usually is the administrator. Name the actual role or action.
- **Limit "please."** It is allowed, but starting every action phrase with it
  is not appropriate.
- **Avoid possessives.** Not *the server hardware's power is off*.
- **No run-on sentences.**
- **No internal terminology in external messaging.**
- **Do not use a resource's name as an adjective.** Write *the uplink set "ABC"
  has…*, not *the ABC uplink set has…*.
- **Avoid "input" as a noun in instructions.** Write *Specify a valid
  certificate*, not *Specify a valid certificate as input*. Write *One of the
  parameters is null*, not *One of the input parameters is null*.
- **Parentheses:** no spaces inside, spaces outside. *this is bad (yes it is)*.
  The exception is constructions like *server(s)*.

## Term list

Spelling and capitalization that must be exact:

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

Word choices:

| Do not write | Write |
| --- | --- |
| app | application |
| internal error | unexpected problem |
| & | and |

Distinctions:

- **"Log in"** is a verb: *Log in to the server*.
- **"Login"** is a noun or adjective: *The login token has expired*.
- **"Filesystem"** is one word.
- **"Host name"** is the name of a host. **"Hostname"** is the Unix command.

## Do not apply these rules to documentation

Worth stating, because it causes real friction: these rules are tuned for
**short strings inside a running product**. They are not a house style for
prose.

If your team already has a writing standard for docs, specs, or release notes,
expect it to disagree with this page in places. HPE wants contractions and a
conversational register in UI text, mandates a specific capitalization scheme
for labels, and permits constructions (*please*, used sparingly) that a tighter
prose standard would cut.

Neither set overrides the other, because they govern different artifacts. Apply
the one that matches what you are writing. A button label follows this page. A
design document does not have to.

## Open questions

- Is there an approved localization process for UI strings, and does the
  sentence-case rule survive translation into languages with different
  capitalization conventions? The site has an `internationalization` template
  page that may answer this.
- Does HPE run a copy review gate before a product UI ships, or is voice and
  tone self-policed by the product team?
- The term list is short and clearly grown by accretion. Is there a longer
  internal HPE terminology database that supersedes it?