Writing Style
Personality
When writing copy for Alation, in general think of Alation as a friend who's:
- Intelligent
- Efficient
- Empowering
- Approachable
- Trustworthy
- Delightfully quirky
Embrace the little touches of humanity that make a product feel approachable, and make our users smile where we can.
e.g. "Ludicrous mode," or fun empty state messages.
Avoid being quirky in scenarios where the user may be stressed.
Ask yourself, would this friend say it like that? Use this as framework for our building blocks for our writing style.
Keep it Simple
- Use the simplest words that your target audience would understand
In general, if you’re not really sure exactly who the audience will be using an interface the most, err on the side of using simple words that everyone understands, regardless of audience or background.
- Only use common abbreviations and acronyms
Use abbreviations and acronyms only when it's reasonable to assume your entire audience would know them.
✅ "LDAP"
❌ "JDBC"
It's good practice to write out the full term on first use of the acronym, e.g. "Key Performance Indicator (KPI)"
- Avoid jargon
Don't expect your audience to all be experts steeped in the jargon of their field. Use words that are understandable by the most people possible.
- Be super concise
Less is more really applies here. Always err on the side of brevity. Be short, sweet, to the point. Continually ask, does the average (90% case) user really need to know that?
- Use common contractions
✅ "Don't, Can't"
❌ "Do Not, Can Not"
- Avoid jargon & "developer language"
Don't expect your audience to all be experts steeped in the same jargon that you are. Use words that are understandable by the most people possible. Overly technical or complex language is alienating.
1st vs. 2nd vs. 3rd Person
Rules of Thumb: When to use “me/you/they"
- First person (I, me, my) — Use for labels, actions, and other static UI where it is expected that the user will not interpret it as a direct message from Alation.
- Second person (you, your) — Exclusively use for messages, errors, and statuses that are communications ‘from Alation.’
- Third person (they, their) — Use when the interface is referring to someone (a real person) that is not the current active user.
Never use first-person plural from Alation. We are not the Borg.
Do not use first person plural (we, us) in messaging. This makes Alation sound like an eerie collective. When writing messages from Alation, use the third person, or avoid pronouns altogether.
✅ Good — “Only showing the first 1000 rows”, “Your biological and technological distinctiveness will be added to Alation”
❌ Bad — “We’ve only shown the first 1000 rows”, “We will add your biological and technological distinctiveness to our own”
Examples by Type
- Labels (1st) — “My Inbox”, “My Stewardship Dashboard”
- Actions (1st) — “Add to my Inbox”, “Change my display name”, “Send to me”
- Messages (2nd) — “Your query has finished running”, “Your admin privileges have been revoked”
- Alation System Errors (3rd)— "Alation has experienced a problem. Its server is not currently responding."
Active vs. Passive Voice
Avoid the passive voice wherever possible.
Whenever possible, don't phrase messaging with the passive voice. Using the active voice results in clearer, more succinct messages. This helps maintain brevity and clarity, especially for non-native English readers.
Capitalization, Style & Grammar
- For titles: Use Title Casing
- For body: Use sentence casing
- For buttons: Use sentence casing
- For Alation Product Names: Capitalize them in accordance with marketing
For grammar and style questions please consult the Chicago Manual of Style and Words into Type, both of which are available in the Alation Library.
Spelling
Alation seeks to use standard American English spellings for words. Consult the American Heritage Dictionary for questions on spelling. It is available in the Alation Library.
Never Insult the User
- Don't second guess
Avoid phrases like: “Are you sure you want to add ’Sean Doe’ as steward?”. Instead, say: “Add Sean Doe as a steward?”
- Use inclusive pronouns
When using the third person, use the singular "they" (and equivalent possessive etc.) when referring to any user.