Writing Style
Voice & Tone alpha

Personality

When writing copy for Alation, in general think of Alation as a friend thats...

  • Intelligent
  • Efficient
  • Empowering
  • Approachable
  • Trustworthy
  • Delightfully quirky

    This does not mean always be silly or playful. That wouldn’t be delightful. Nor does this mean be quirky for quirky sake. Again, this wouldn’t be delightful. This means we should embrace the little touches of humanity that make a product feel approachable, and make our users smile. Think the genie effect on Mac when closing a window. Or Ludicrous mode on a Tesla. Or the illustrations on Google Hangouts for empty states. Each one of these doesn’t make the product seem silly or like a toy, and if it wasn’t pointed out to you, you probably wouldn’t notice it, but it does add a touch of humanity making the product feel both more polished and more approachable.

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 everyone at the most elementary level of 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.
  • Use basic abbreviations and acronyms
    Use abbreviations and acronyms that everyone at the most elementary level of your target audience would understand. If there isn’t an abbreviation or acronym simple enough, write it out.
    Good: LDAP
    Bad: JDBC
  • Avoid jargon
  • 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 contractions
  • Don’t use developer language
    At the end of the day, our users just want to get something done. They don’t care about the implementation details. Write for the user.

Capitalization & Spelling

  • 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

If you’re not sure how to treat a word, see The American Heritage Dictionary, The Chicago Manual of Style, and Words into Type (all available at the Alation Library). If there are conflicts, use the Chicago Manual of Style for questions on usage, and the American Heritage Dictionary for questions on spelling.

Never insult the user

  • Assume the user knows what they did
    Stray away from phrases like: “Are you sure you want to add ’Sean Doe’ as steward?”. Instead, say: “Add Sean Doe as a steward?”
  • Use quotes respectfully and cautiously
  • Avoid misgendering
    If you are certain a user identifies as a male or female, use the proper gendered pronoun.
    If you’re not sure if someone identifies as a male or female use gender ambiguous language such as “their” and “they”.

Changelog

  • December 4, 2017 - Added rules for button casing
  • December 9, 2016 - Promoted to Alpha