Writing Guidelines

Principles of writing

1. Help users, by telling them what to do next.
2. Keep it simple, clear, and concise.
3. Put the most important information first.
4. Write like a person and avoid obscure terms.
5. Be consistent.

General styling

Objective then action

• If a sentence describes an objective and the action to achieve that objective, start with the objective.
  • Ex: Drag a photo to the trash to remove it from this album should be To remove a photo from this album, drag it to the trash

Verbs

• Avoid passive verbs
  • Ex: The request form must be submitted should be You must submit the request form

Audience

• Use imperative for instructions
  • Ex: Upload a file to import inputs
• Use contractions
  • Ex: Your changes won't be saved
• Address the user as "you"
  • Ex: Are you sure you want to abort this workflow?

Length

• Keep sentences short, 20 words or less
• Keep paragraphs short, 2-5 sentences max
• Keep it simple! Wordy instructions are harder to follow

Capitalization

• Headings use sentence capitalization
  • Ex: Error uploading notebook
• Specific technologies:
  • JSON file, JSON formatted data
  • .ipynb file
• Button labels are no longer all-caps (so "Ok" instead of "OK").

Commas

• Oxford comma
  • Ex: This book is dedicated to my parents, Ayn Rand and God should be This book is dedicated to my parents, Ayn Rand, and God

Period (full stop)

• End a user-facing complete sentence with a period (.), unless it's a question.

Spacing

• Use one space between sentences

HOW TO's:

Error messages (Humble, Human, Helpful)

Part 1: Short and high-level notice

• Make it clear if it is an Error, Warning, Notice, Success, etc
  • Ex: Error processing file

Part 2: More detail

• Give the user more background about what went wrong and if there is something they can do better or differently
  • Ex: This JSON file is not formatted correctly.

Labels

Omit colons after labels, they shouldn't be necessary

Helpful resources

• Google's Material writing guidelines

And when in doubt, ask Brad!