UI text / wording guideline

[thisismydesign]

A guide on UI text / wording would be nice. I'd prefer that we find and re-use some exiting reputable guide. Would only start deciding on our own as a last resort because it's a fairly contentious topic.

E.g. whether to use sorry and please is usually a topic of discussion.

Sorry, something went wrong. Please try again later.

vs

Something went wrong. Try again later.

Other topics:

• capitalization of text
• tone
• pronouns
• etc

[thisismydesign]

Clarifying the scope and goal of this guide:

This guide is made for developers. It is not to address concerns of branding or copy writing.

Why do we need this?

• it is important to have unified and clear wording even during early stages of development or prototyping
• when building a brand around a prototype it is easier for copywriters to work with already existing, unified text
• in some cases it is ok for developers to write the final copy if they have a baseline (mainly for smaller projects or restricted audience such as an administration tool or log messages)

[TelegraphEve]

RULES AND TIPS

The ideal UI text is:
• Consistent with existing Qt Creator UI terms
• Short, concise, useful and easy to understand
• Neutral, descriptive, and factually correct
• Unambigious
• Translatable into different languages

1.) Begin with the objective
Don’t: Tap on item to see it’s properties
Do: To see item’s properties, tap on it

2.) Use specific verbs whenever possible
Specific verbs (such as 'connect' or 'save') are more meaningful to users than generic ones (such as 'configure' or 'manage').

3.) Make the copy consistent
a) If you decide to call the process of arranging something 'Scheduling' in one part of UI do not call it a 'Booking' in other parts of your UI.
b) Don’t refer to the user in both the second person and the first person within the same phrase.
Don’t: Change your preferences in My Account
Do: Change your preferences in Your Account

4.) Write in the active voice
Don’t: The Search button should be clicked when you are ready to search for an item.
Do: Click the Search button to search for an article

5.) Identify interactive elements appropriately
When labeling buttons and other interactive elements, use action verbs, such as ‘Connect,’ ‘Send,’ ‘Subscribe’ instead of vague ‘Okay’ or ‘Submit.’

6.) Use language that’s consistent with the user’s platform
The terms we use when describing interaction with a desktop app do not necessarily apply to mobile platforms. For example, if you design an iPhone app, we can’t say ‘click’ when referring to the action. We need to say ‘tap’ instead.

7.) Grammar and Style
All UI text must be grammatically correct English and use the standard form of written language. Do not use dialect or slang words. Use idiomatic language.

8.) Punctuation

• Use full stops in messages.
• Place three full stops (...) at the end of menu item names that open a dialog requiring user action.
• Use exclamation marks (!) only in text that demands extra attention from the user or carries special weight.
• Use quotation marks ("") around variable values. For example, Close Project "qtcreator". For consistency, use double quotes to emphasize or set apart file names, directory names, URLs, and so on, in user visible strings.
• Do not use leading, trailing, or multiple spaces to align text in messages, as translation tools might not handle them correctly.

WHAT TO AVOID

1.) Jargon Words and Specific Terms (‘geek speak’)
Write for all levels of readers: pick common words that are clearly and easily understandable to both beginning and advanced users. It’s especially important to avoid jargon in error messages.
Don’t: System error (code #2234): An authentication error has occurred
Do: Sign-in error: You entered an incorrect password

2.) Long Content Sections With a Lot of Details
Keep sentences under 30 words when possible. In most cases, it’s not necessary to describe every detail in the first interaction. Write in small, scannable segments to facilitate discovery.

3.) Using the Future Tense to Describe the Action
Use the present tense to describe product behavior. When you need to write in the past or future, use simple verb forms.
Don’t: “Message has been sent”
Do: “Message sent”
Don’t: Video has been downloaded
Do: Video downloaded

4.) Mixing “Me”/”My” With “You”/”Your”
It can cause confusion to see both forms of addressing the user in the same context.
Don’t: “Change your preferences in My Account.”
Do: “Change personal preferences in My Account.”

5.) Using Words For Numbers
Save screen space !
Don’t: “You have three messages”
Do: “You have 3 messages"

6.) Pronouncing “We”
a) Focus on the user and what they can do with your app, rather than what you or your app is doing for the user.
Don’t: “To get you started, we’re showing you popular posts on Facebook.”
Do: “Get started with these popular posts on Facebook.”

b) Exception: when a human actually does take action for a user, such as reviewing an appeal or responding to a suggestion.
Don’t: “Your appeal will be reviewed, and you will receive a response within a few days.”
Do: “We’ll review your appeal and respond within a few days.”

7.) Capitalizing All Letters
Thus, use sentence-style caps for all titles, headings, labels, menu items.
Don’t: “SEARCH SETTINGS”
Do: “Search settings”

8.) Absolutes and Over-promising
Never say “never” is a great rule to follow.
Don’t: “We’ll never send you promo emails”
Do: “You’ll receive only important information”

Don’t brag — reveal what a feature does, but don’t say how great it is.
Don’t: “Amazing deals at places you’ll love”
Do: “All your savings in one place”

9.) Exclamation Points
Exclamation points should be avoided as they could come across as shouting.
Don’t: “Learn about the new features of the app!”
Do: “Welcome”

10.) Gender Ambiguity
Be specific about gender whenever possible — use his or her.

11.) Common Introductory Phrases
Use simple, direct language that is easy for users to understand. All extra or common introductory phrases such as ‘you must,’ ‘due to the fact that’, ‘in order to’ should be omitted.
Don’t: “Would you like to save your changes?”
Do: “Save changes?”

12.) Double negatives
It’s confusing and unnececary.
Don’t: I do not want to unsubscribe

13.) Addressing the user in the second person
Use a neutral tone or passive voice but use a formal address when necessary.

14.) Using the word 'Please' when addressing the user
Exceptions to this are some copyright text and short imperative sentences that might otherwise sound abrupt. For example, 'Please wait.'

15.) Abbreviations in the menu names and items
If there is no room for the full spelling or hyphenation of a word, abbreviate the text according to the English abbreviation rules.

16.) Using punctuation marks or special characters in menu names and items

17.) Unnecessary content words and phrases
UI text should be concise and economically formulated.

IF YOU WANT LEARN MORE...
https://doc-snapshots.qt.io/qtcreator-extending/qtcreator-ui-text.html
https://uxplanet.org/effective-writing-for-your-ui-things-to-avoid-f6084e94e009
https://uxplanet.org/16-rules-of-effective-ux-writing-2a20cf85fdbf
https://material.io/design/communication/writing.html#writing-for-components
https://docs.openstack.org/doc-contrib-guide/ux-ui-guidelines/ui-text-guidelines.html
https://medium.com/google-design/creating-ui-text-that-translates-5f113ffb7c43

[thisismydesign]

Further resources:
https://www.gov.uk/service-manual/design/writing-for-user-interfaces
https://docs.openstack.org/doc-contrib-guide/ux-ui-guidelines/ui-text-guidelines.html
https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/terminology/
https://about.gitlab.com/handbook/communication/#user-communication-guidelines