Sign in, Sign in to
Avoid: Login, sign-in, sign in, sign into,
Sign up, sign up to
Avoid: signup, sign-up.
Marketing material may occasionally use the calls to action: "join at/here" or "register to/at". But the documentation and the system itself MUST always use the term "sign up".
Sign out
Avoid: Logout, sign-out, signout.
Customer
Person or organization in charge of one of more billing accounts.
Member
Person who belongs or subscribes to a particular group or organization. These normally are registered under paying customers' accounts.
User
Person not registered to the platform, but user of one of the products that doesn't require registration.
Customer vs member vs user
Initech Corp. is a paying customer of the platform and their DBAs are members of the Platform.
Acme Inc. uses some of our product that don't require registration to the Platform. Acme Inc's staff and contributers are users of our Products.
Bob is a contractor DBA and signed up to free-tier Platform. Bob's clients are small businesses mostly running a small number servers each. Bob hooks his clients' servers to his account so that he can monitor them from a single place. Bob is a customer and a member of the Platform.
-
De facto language: US English.
-
Punctuation MUST be used in all messages, except for headlines. See notes regarding accessibility and screen readers.
-
Only capitalize the first letter of an element's copy. All references to the element MUST follow the exact same format.
We have a button/link element labeled Forgot password. Let's say that the copy related to the 'forgot password' feature would read: Click Forgot password to reset it. Notice the capital 'F' in Forgot, following the exact same format as the button/link.
- Avoid harsh language tone within the UI.
| Bad copy | Acceptable copy |
|---|---|
| You must change this | Please review the value entered |
Example: A field that recommends values within the range 1-8 and throws warnings for 9-10.
When the user enters '9' through the UI:
| Bad copy | Good copy |
|---|---|
| Value too high. Are you sure? [Confirm] [Cancel] | The value entered is above the recommended range. [Confirm] [Cancel] |
| " | The value entered is above the recommended range. Please confirm that you would like to proceed with it anyway. [Confirm] [Cancel] |
When the user enters '9' through the API (notice that there's no secondary confirmation):
| Acceptable copy | Better copy |
|---|---|
{"code":200,"message":""} |
{"code": 200, "message":"Warning: the value entered is above the recommended setting."} |
- When an error message cannot specify the exact source of the problem, the use of unique identifiers as part of the message itself is recommended. This is because searching the source code for 'sign-in failure' or 'access unauthorized', for example, may yield dozens of results. While searching for a unique string like 'A1B2C3', '888CCC' will get the developer to the exact line of code when they are debugging issues.
This approach also helps the support team troubleshoot, since unique references can be associated with a particular root cause more easily.
Example: A user may be unable to sign-in due to several reasons. And for security reasons, we cannot tell the user whether their email address was/wasn't found in our database because that would leave us open for possible address verification exploits.
| Bad copy | Good copy |
|---|---|
| Sign-in failure. Invalid email or password. | Authentication failure. Try again or click Forgot password to reset it. (#88899) |
| Sign-in failure. Connection timeout. | Authentication failure. Try again or click Forgot password to reset it. (#AAABBB) |
- When the error is final, we MUST NOT ask the user to 'try again'.
| Bad copy | Better copy |
|---|---|
| Account not found. Please try again or contact your domain administrator. | Account not found (#A1B2C3). |
- https://accessibility.blog.gov.uk/2017/02/08/advice-for-creating-content-that-works-well-with-screen-readers/
- https://developers.google.com/style/accessibility
- https://www.nngroup.com/articles/ui-copy/
- https://brentwrites.com/saas-writer/
- https://uxplanet.org/grasping-the-interface-language-67a711eb6867