THIS IS NOT A STARTER DOCUMENT. THESE ARE NAPKIN SCRIBBLES.

Vocabulary

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.

Styling

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

mvsantos/PRODUCT_STANDARDS.md

THIS IS NOT A STARTER DOCUMENT. THESE ARE NAPKIN SCRIBBLES.

Vocabulary

Styling

Resources: