Skip to main content

Writing for user interface

We always speak in a way that reflects our brand and values. The words we choose always put our users first, helping them better understand, navigate, and find value in our products.

Brand voice​

The brand voice reflects the attributes that define Schneider Electric. By infusing communications with our brand personality, we ensure that audiences perceive a consistent company persona that memorably stands for the same values.

These Schneider Electric brand voice principles, help us write with purpose:

  • Be Authentic
  • Be Concise
  • Be Relevant

See the full Brand Voice guidelines on the Brand Portal.

Interface guiding principles​

The interface is your assistant, not your friend. As a good servant, it knows the user's needs and anticipates them. Humble, it doesn't showcase its work and only speaks when necessary while remaining available at all times. When addressed, it is polite, concise and conversational.

Following these principles will help us write with purpose:

Smart

Using concise and simple words and sentences. Avoid any jargon and confusing terms. Be straightforward.

Reassuring

Always use a calm tone when conveying critical information. Be warm but down to earth. Provide solutions rather than showing problems.

Contextual

What is most helpful? What is most relevant? Who are you writing for? What are you writing about?

Human

Advise, don't impose. Speak with the user instead of at them.

UX writing​

As Jason Loo, a Victoria-based UXer always says: "Content drives design".

Text and the words that are used in the interface are part of the design, and thoughtful UX writing adds context to visual interfaces. It is about consistently using the right words to communicate with a given audience.

User experience (UX) writing consists of all the strings that appear in the user interface (UI). UX writing includes: window and dialog titles, headings, labels, UI control text, descriptive text, information and error messages, and additional help text (such as tooltips or hover text). UI strings must be concise, clear, and consistent (and safety reviewed). Review the topics in this section to broaden your UX writing understanding.

UX writing approaches and tools​

Strategic Writing for UX is an approach described by Torrey Podmajersky in her book by the same title. The book discusses the entire UX content creation process. It includes tools such as Voice Chart and UX Text Patterns that can help you write consistently high-quality text.

Use the following resources to get started with this approach to UX writing:

  • Book notes on the key aspects and tools described in the book (Notepad text notes in Box)
  • UX Writing Toolkit with Scorecard template, Voice Chart template, Voice Chart examples, and more (Excel Workbook in Box)

General rules​

Clarity & Consistency

  • Short, clear sentences. The shorter the sentence, the easier it is to translate. English is shorter than most languages; an average length English sentence may result in a very long sentence when translated, impairing understanding.
  • Write dates and times in unambiguous and clear ways.
  • Be consistent. Use the same word if it refers to the same thing in different places.
  • Don't use the same word to mean different things. In particular, avoid using the same word as both a noun and a verb in close proximity.
  • Avoid abbreviations. Abbreviations can be confusing out of context, and they don't translate well.

Strings

  • There are no spelling mistakes.
  • All words are written in US English.
  • Words are clear and reduce ambiguity (there is no jargon nor "insider" acronyms.)
  • Words are used and applied consistently throughout the UIs and dialogs.
  • Words are not forbidden. See Word list for details.
  • Words are inclusive.

**Inclusive writing **

We write our documentation with inclusivity and diversity in mind. This page is not an exhaustive reference, but describes some general guidelines and examples that illustrate some best practices to follow.

  • Avoid unnecessarily gendered language. In addition to being mindful of the pronouns used in narrative examples, be sensitive to other possible sources of gendered language.

    Equipment installation and setup takes approximately 16 man-hours to complete.

    Don't

    Equipment installation and setup takes approximately 16 person-hours to complete.

    Do

  • Avoid ableist language. When trying to achieve a friendly and conversational tone, problematic ableist language may slip in. This can come in the form of figures of speech and other turns of phrase. Be sensitive to your word choice, especially when aiming for an informal tone. Ableist language includes words or phrases such as crazy, insane, blind to or blind eye to, cripple, dumb, and others. Choose alternative words depending on the context.

  • Avoid being too culturally specific. Be mindful when referring to specific holidays, cultural practices, sports, figures of speech, etc. Being sensitive here also supports writing for a global audience. Take care to choose a diverse set of names to help examples reflect the real world diversity of our audience.

  • Write about features and users in inclusive ways. Avoid referring to people in divisive ways. For example, instead of referring to people as "native speakers" or "non-native speakers", consider whether or not your document needs to discuss this at all, and revise in order to discuss the feature in terms that are relevant to anyone, regardless of what languages they know.

  • Avoid using socially-charged terms for technical concepts where possible. For example, avoid terms such as blacklist and first-class citizen, even though these terms may still be widely used. Instead of first-class, consider other terms such as: core feature, built-in, top-level. Choose the best term for your context.

Spelling

  • Use standard American spelling. Where American spelling differs from Commonwealth/"British" spelling, use the American spelling.
  • When in doubt about the spelling of a word, see the Merriam-Webster's Collegiate Dictionary.
  • Avoid non-English words or phrases, such as de facto or ad hoc.
  • Avoid Latin abbreviations for common English phrases. Exception: It's OK to use etc., in situations where space is limited. Otherwise, see and so on for alternatives.

SEO

  • Write for our audience, not for Google.
  • Use headings to appropriately structure content in a logical, parseable way.
  • Every image should have alt text.

Slang & Terminology

  • Avoid slang. Write in plain English.
  • Technical terms should always be accompanied by a clear definition.

Acronyms

  • Always spell out acronyms word-for-word the first time they're used.
  • First use: Information Technology
  • Second use: IT
  • No need for a parenthetical.

Grammar

  • Proper grammar promotes clarity and helps us speak in a professional voice.

Active Voice

  • Always use active voice over passive voice.

Alt Text

  • Every image should have alt text.
  • Alt-text briefly describes an image in one or two sentences.

Safety

  • There are no critical (or reserved) words.
  • There are no safety-related icons.

Reviewing user interfaces​

Review the strings in the User Interfaces (UIs) for safety, spelling, and consistency. When reviewing UIs, your feedback should be constructive and professional. A good strategy to use is to ask questions which will prompt further discussion. Softer terms like "consider the following" helps keep the dialog open.

To review UIs:

  • Obtain all the strings from Dev.
  • Review the strings for safety.
  • Review the strings for spelling mistakes.
  • If you find issues, work with the team to edit the offending terms.
  • Review the UI logic and flow.
  • Review form elements; make sure they follow best practices.
  • Work with UX and Dev to edit the UI.

Minimal UI review​

At a minimum, review UI strings for safety and critical word usage, and spelling. A string is a word that appears in the UI. Strings include titles, labels, phrases, etc. Strings also include all the words in dialog and error messages.

Key point: A lot of message boxes don't appear unless you perform a very specific set of clicks. For this reason, it is important to obtain the RESX files to see ALL the strings, not just the common ones.

Optional UI review​

If you are working with UX and the Dev team has time to edit the UI, review the UIs for logic and flow, review forms for customer experience.

A quick way to know whether a workflow needs to be reviewed is if the task has more than 10 steps. The number of steps is directly related to complexity.

A form is a UI element that can collect user information. Forms are comprised of text fields, check boxes, and other interactive elements such as drop-downs.

Collecting trivial information or making non-essential information mandatory is a symptom of poor design. Root it out whenever possible.

The UX writing section is based on the work of Robert Thibodeau et Marcus Gasper for Ecostruxure TechComm BoK.

Headings & Subheadings​

  • Use headings and subheadings to announce
  • Use short informative sentences to summarize the content: what it is, where it is, in which state.
  • Don't use punctuation unless the title is a question.
  • Relevant keywords should be included in headings, but SEO should not be the only factor considered when writing. We should speak like humans.
Titles saying 'Hello, all is working well'.
Example of conversational titles.
  • The tab titles are consistent (all nouns or all verbs).
  • The left to right tab order follows the user workflow.
  • Keep the section name to one or two words.
  • Clarity is key. Avoid ambiguous marketing-speak.
Three mobile tabs labeled: Home, Energy, Settings.

Example of navigation tabs for a mobile application. All the tabs use nouns as labels. Home is almost universally the left-most tab. Settings is almost universally the right-most tab.

Buttons​

  • Always include an action verb
  • Avoid ambiguous actions like "learn more", "see more"
  • Always be clear and concise
A dialog box with a 'See more' button
Don't
A dialog box with a 'Go to task details' button
Do
  • Include a link whenever referencing external content.
  • Avoid phrases like "click here." Instead, use language that describes the content you're linking to.

Click here to configure the thresholds.

Don't

Thresholds can be configured in the XYZ settings section.

Do

Forms​

  • Labels should be clear and concise.
  • Mandatory information is more prominent than optional information.
  • Mandatory fields are clearly marked as such.
  • Non-essential information is not mandatory.
  • Text fields contain sample values (usually in italics and a lighter font color) to help users understand what info needs to be added.
  • Explanatory tooltips are available when (and proximal to) the term is very technical or potentially ambiguous.
  • A user-acknowledged GDPR statement is included when the app collects personally identifiable information.
Small form with two generic fields and two validation messages: one error message 'Entry not saved', and one success message 'Changes saved'.
Example of form

Dialog boxes​

  • Error messages follow best practices. See Writing error messages for details.
  • The dialog button labels are clear and present the user with a clear call to action or choice.
  • The 80% action uses the higher style in the button hierarchy (typically Primary).
Dialog box entitled 'HVAC_1 is over temperature', with informational labels, an 'Inspect alarm details' button and a green emphasized button labeled 'Create a task' with an icon.
Example of dialog box

Error Messages​

Error messages can be tricky to write. The user who made the error could be very frustrated, so aim to make the message as empathetic as possible.

A good error message consists of the following components:

  • What has happened
  • Why the error occurred
  • What can be done to prevent it happening again
Notification message saying 'Update installation failed due to a network issue', with a 'Close' button.
Example of a notification message

The following websites include great tips on how to write error messages:

Last updated on