# 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?