Writing Style Guide

How to win enemies and influence friends

How to sound familiar

Every time we interact with our users it reinforces their perception of Robin. When our copy's tone is consistent, we make it easier for users to get to know us and adopt new features quickly. This guide will help you bring our approach into your work.

What sort of people build Robin? What sort of person are we trying to help? In many cases our customers come from a world where design and human-language are luxuries they get after 5pm. Professionalism comes in many forms, and it sure as hell isn't through robotic phrasing and templated "Sorry for the inconvenience" responses 8 hours after the problem started.

If Robin was a person it would celebrate the success of its friends before mentioning its own accomplishments. Robin knows that people get tired of phony #brand talk. It would rather be measured and deliberate than frequent and loud. We speak when we know something. If Robin was a person, it would be the friend you'd like to see more of, instead of the one you regret taking on a road trip because they talk too much.

Four Values in Our Writing

Brevity

We are direct in our explanations, making us quick to respond. We ask questions and speak in 2-3 sentence bursts. Request one thing at a time, unless referencing an existing doc. This improves understanding and makes progress (and confusion) easy to spot along the way.

If you're active in a conversation, responses shouldn't take longer than 20-30 seconds to send.

Do

IT Manager: "I keep getting an error whenever I try to end a meeting early"
Robin: "Yikes. Do you know who made this calendar originally?"
IT Manager: "I think my assistant did."
Robin: "Got it. Fortunately this is super fixable. Just a moment."
IT Manager: "Here's a handy guide to update permissions: https://support.robinpowered.com/hc/en-us/articles/206441133"

Don't

IT Manager: "I keep getting an error whenever I try to end a meeting early"
Robin: "I have a few things you can check first. Are you an administrator? Did you make the calendars yourself? Sharing settings are typically the most common place where errors occur. You can also find a copy of these steps in our support docs here: https://support.robinpowered.com/hc/en-us/articles/206441133. Let me know when you're done and we can continue.
IT Manager: "I'm going to have to come back to this later."

Levity

You won't always be funny, charming, or appreciated. The gesture is what matters, and it sets the tone. Take risks and don't be afraid to poke fun at yourself. Avoid campy, cliche, or slapstick jokes.

Do

"I don't know much, but I do know my Office 365 configurations. And yes, I'm a riot at parties."

Don't

"Are you working hard or hardly working?"

Empathy

We are not why people come to work every morning, but we are a stepping stone towards getting the important stuff done. Features and troubleshooting are a team sport, and our approach should feel like a cooperative effort. Use "Let's" and "We" liberally, and be the first to acknowledge when a process is frustrating. You are doing it with them, not to them.

We use emoji and images to make higher impact. We also respect ourselves by avoiding language that make us read like a middle school texting conversation. Less "LOL YAY!!!" and more "Great job!". Avoid campy "rah rah" and in favor of measured and specific admiration.

Do

"Company culture takes hard work, but [Company] has a simple approach to making it happen. Check it out: [Link]"

Don't

"Check out these amazing and innovative tips from a company that definitely knows how to have fun!"

Comprehension is a personal journey. You score points by making the other person look smart, not yourself. Assume the other person knows what they are doing, but give them outs. Framing things in terms of "In our world, we call it... but your setup might be a little different." gives people an opportunity to ask for help without feeling dumb.

Do

"Did you see any specific errors when you tried the first time? If not, I can link you to a guide for getting extra info from your service."

Don't

"What did your EWS admin panel logs show? Did the account imperonation fail or is it a delegate?"

Utility

Nobody cares if we ship a new version of the app. They care what it helps them do. Be quick to volunteer how changes affect people, and avoid adding noise when no measurable impact exists. It is better cadence to make someone's day infrequently than to fanfare noise daily.

Titles & Emails

Titles longer than three words should be sentence case. If the title starts with a number, capitalize the first word instead.

Do

"Five tips for scheduling meetings"
"5 Tips for scheduling meetings"

Don't

"Five Tips for Scheduling Meetings"

Titles should avoid trailing punctuation unless absolutely required:

Do

"How should we manage our conference rooms?"

Don't

"Five tips for scheduling meetings."

Buttons

Short buttons should be in title case. Longer than three words should be sentence case. Almost all buttons should aim for 3 words or less while being as precise as possible.

Do

"Save Changes"

Don't

"Save changes"

Buttons should describe the action they perform in terms of the user. In these examples, assume this button is on a form for inviting others to your organization:

Do

"Send 5 invites"
"Invite"

Don't

"Save Changes"
"Submit"

Errors

When delivering messages about errors or constraints, phrase it in good faith. An easy example is ending sentences in "yet" when the current state of affairs isn't ideal. It's also an easy way to frame errors in terms of their resolution:

Do

"You haven't been invited to this organization yet"

Don't

"You don't have permission to view this organization"

Addressing others

Everyone is an ageless, genderless being until proven otherwise. Avoid using gendered terms such as "guys" in favor of "folks". Avoid assigning a gender to someone based on name (i.e. Alex) or role (e.g. IT Director) alone.

Do

"Which error did they see?"

Don't

"Which error did he see?"

Apologies

A good apology is genuine, and avoids hiding behind professional soundbites like "We do apologize for the inconvenience..." Always favor "Sorry" over "Apologize", and don't apologize for the other person. "I'm sorry you feel that way" is for Slytherins, not the house Robin.

Do

"Sounds like we could do a better job of communicating this, and I'm sorry for the trouble. From here, we can…"
"This shouldn't have happened, and I'm sorry you had to start your day like this."

Don't

"I'm so sorry you're mad."
"Please accept Robin's apologies for the inconvience. We value your business as a customer."

Authenticity

The secret to authentic apologies? Knowing when you shouldn't apologize. When you save apologies for the stuff that matters, you make sure it carries the value we'd need it to convey. When you're quick to apologize for everything, it loses impact. Use apologies sparingly... just not too sparingly.

Inconveniences often don't need apologies — just an earnest indicator you're ready to help.

Do

Alice, the user: "I got logged out again..."
Support, from Robin "Yikes, that's definitely not what we're going for. Let's figure out what the trouble is."

Sorry as a verb

An apology is an opportunity to help. Everything you do should work towards a resolution. If you think the other person may want to vent without finding a resolution, try dismissing yourself from the conversation in favor of action. It may not be immediately appreciated, but action is the best way to show our commitment to customers in the long run.

Do

Alice, the user: "Not a good look for your reputation. If this continues I'm going to look at competitors."
Support, from Robin "Got it. This sounds urgent, so unless there's something else I can help with in the meantime, I'm going to go address this now."

Questions

A high quality question includes context, and lead to a specific request. Most questions aim for a specific fact, recommendation or process. A good question is closed when confirming progress (e.g. "Is this link correct?") and open by default (e.g. "What's the best way to...?").

A high quality question is a great way to show respect for the recipient's time and expertise. You should, of course, avoid the opposite.

Do

"How do I set up a new account?"
"Where does Alice sit?"
"I just tried the guide with no success. What's the best way to troubleshoot my wifi connection?"

Improving your question quality

A low quality question is frustrating. It's poorly framed, ambiguous with the request, and requires follow up questions to clarify. It is often unintentionally closed (i.e. Yes or No answers) or more implication than actual question. Low quality questions make you seem passive aggressive, or at the very least disengaged.

Don't

"I can't find my member list..."
"Do you see any errors on my account?"
"I can't log in. Thoughts?"

"Thoughts?" And "Please advise" are lazy questions, because they delegate not just the answer but also the process of identifying the main issue and/or question. This may be a byproduct of habit from "Fwd: Re: Problem" email delegation shuffles, but the end result is slower time-to-solve since the thread starts with secondhand information.

Some questions will remain abstract and need finesse to arrive on properly. Make the effort anyway — your teammates will appreciate the gesture.

Emphasis

Font styles such as italics and weight are tasteful (yet powerful) ways to communicate emphasis without overloading hyperbolic language and punctuation. Elements of Typographic Style is a great handbook for learning these techniques. We have a copy available in the office.

You should never write in ALL CAPS unless you are:

  • Working on engineering copy (i.e. "Hi NAME, welcome to COMPANY")
  • In the 90's and forwarding a chain email for the first time
  • A maniac
  • Enthusiasm

    You get one exclamation point per message. Use it wisely, and avoid using it on phrases which may be misconstrued as "yelling" or "disciplining" the user. It is easier to appropriately use exclamation points on positive messages.

    Do

    "Nice work! You ended the meeting 20 minutes ahead of schedule."

    Don't

    "You can't create that meeting right now!"

    Phrasing

    Consistent explanations improves onboarding UX. Synonyms may seem obvious to people familiar with the product, but may cause unnecessary confusion with newcomers. Where possible, we should use the preferred phrases in this section.

    Spaces

    Use "rooms" only when referring to types of spaces, or overall inventory. You can add rooms as spaces in Robin, just like you can add auditoriums, patios, and cafeterias.

    Do

    "When you search for space in your office, Robin finds available rooms and on-demand areas around the office."
    "Search spaces in your office"

    Don't

    "Search rooms in your office"

    With calendars

    For employee-facing UI use "Bookable space" when referring to spaces with calendars currently attached (i.e. conference rooms, labs). Bookable space has a calendar attached. They are the most important kind of spaces in Robin apps.

    In some administrative UI you may choose to use "Calendared" or "Has Calendar" to describe the state of a space.The phrase "calendared" is unwieldy and more inventory focused than the user-centric "Bookable" action. Use "Bookable" by for employee-facing apps by default.

    Without calendars

    Use "On demand space" when referring to spaces without calendars attached (i.e. lobbies, kitchens). These spaces will most commonly be occupied/unoccupied only or managed via presence. We consider them as secondary to bookable space.

    Explaining Features

    Outcome over implementation.

    When you're clever, the "how" of problem solving sounds like the exciting part. When you're really clever, you understand that admiration rarely carries over to the average user. Feature descriptions should rarely lead with words like "modal", "button", and "push notification". Good variable names in code won't always well translate to public labels.

    Do

    "Your calendars"

    Don't

    "Visible calendars"

    Do

    "Control the kinds of meetings booked via the room display using the new device management tools."

    Don't

    "Use the new device management modal to update your tablets booking rules"

    Do

    "Turn on presence, and your phone will recognize nearby spaces. Requires Bluetooth."

    Don't

    "Enable Bluetooth to activate presence features through nearby beacons."

    Browsing vs. Searching

    Are you looking for something specific? Or just looking? Sooner or later, you'll come across a feature request or customer problem which touches this problem. Both are distinctly different problems, and we try our best to separate them as features within our apps.

    When you recognize the difference, you'll have an easier time figuring ut where features should go. When you understand the rules for feature development, you can point people in the right direction and get stuff done faster.

    You know the criteria of what you're looking for, but not the specific thing. The results are not predictable, and may change over time.

  • Which rooms are free at 10AM tomorrow morning?
  • What's the best space for a five person video conference right now?
  • Browsing

    You have a specific thing or criteria in mind. The results are predictable, and generally don't change over time.

  • Show me all spaces without calendars on this floor.
  • Let's see what the conference room's phone number is.
  • Where does Alice sit?
  • Presence

    Presence is the way Robin detects who is the in the room, and logs occupancy. Do not use occupancy as a synonym for presence. In most cases the user's definition of occupancy is better served via a combination of schedule and presence analytics.

    It is easier to explain presence in terms of the feature's outcome, and as something you "turn on".

    example

    "With presence enabled, spaces with beacons will recognize people using the mobile app. Robin uses this data to adjust calendars and log occupancy in realtime."

    Being "present" in a room means your app is "reporting" presence. Avoiding using verbs like "publishing" or "posting" since they are biased towards engineering lingo.

    Beacons

    Use the generic "beacons" phrase instead of specialized implementations such as "iBeacon" or "Eddystone". We refer to beacons as a kind of indoor location, and speaking about it similar to how you would GPS will keep conversations clear and concise.

    It is easier to explain presence in terms of the feature's outcome, and as something you "turn on".

    Do

    "Beacons are a way to mark locations inside your building so apps can figure out where you are."

    Don't

    "Buy some iBeacons and their signal will broadcast to nearby devices and let them know details about the location"

    Company

    Refer to our company as "Robin".

    You will rarely encounter a situation (outside of legal) where our full corporate name is appropriate for user-facing material. In these cases where full legal name is required (i.e. footer copyright) it should be in the form "Robin Powered, Inc." including punctuation.

    Apps

    Use "Robin" when discussing the overall system. "Our office runs Robin" When describing specific deployments you may also use the phrase "[Company] is powered by Robin" (i.e. "DraftKings is powered by Robin") This is both a play on our full company name, as well as good framing for the role of Robin as an enabling force in the workplace.

    Avoid using insider phrases like "Dashboard" and "tablet" in favor of more descriptive "The web dashboard" and "Room display app" until you're sure the user understands the references.

    Rooms

    Robin Rooms is a room display app for tablets. Use "room display" instead of using the word tablet as an adjective. While occasionally effective, tablet is a method of deployment and we should focus on the utility of the app instead of method.

    Do

    "Our room display app works on both iPad and Android tablets."

    Don't

    "Our tablet app works on both iPad and Android."

    Mobile

    Robin has a room scheduling app for mobile. It is how employees interact with our scheduling tools. It is listed on the app stores as "Robin Powered", but we should avoid using the full name when discussing it in favor of "our mobile app" and other possessive language.

    Do

    "Your employees can schedule meetings directly using our mobile app"

    Don't

    "Your employees can schedule meetings directly using the Robin Powered app"

    Dashboard

    Robin's web dashboard is a scheduling and office management tool. It's available for both administrators and the teams they support.

    How to download

    Our apps are available for Android and iOS, and we keep up to date links on https://robinpowered.com/downloads. When in doubt, share the link instead of guiding people through the search process. A link is much easier to share among the team than a search query and avoids confusion of tablet vs mobile apps.

    Do

    "Your team can install our mobile app on their iOS and Android phones. Here's a link: https://robinpowered.com/downloads"

    Don't

    "Download by searching 'Robin Powered' on Android and iOS app stores"

    Space Status

    Spaces can have one of four statuses, each with a unique color.

    available

    The space can be used or scheduled.

    booked

    The space has a calendar event, but occupancy is unconfirmed. Nobody has checked in via presence or the room display.

    in use

    The space has a confirmed calendar event or is occupied.

    disabled

    The space is archived and not active in any user-facing features. Only a company's admin may reactivate them.

    Events

    With a few exceptions, we use all of the same phrases Google Calendar does when labeling events. In order to make responses consistent across each calendar service we adjust RSVP states slightly:

  • Attending: Confirmed yes, labeled "Attending"
  • Declined: Confirmed no, labeled "Declined"
  • Tentative: Responded "maybe", labeled "Invited"
  • No response: Hasn't responded yet, labeled "Invited"
  • Availability

    When talking about an available room, focus on the relative time it is open. It is easier to find the right room for a 45 minute meeting when you are thinking in terms of total time available. It should answer the question "How long can I use the room for?"

    Do

    Conference Room is available for 2 hours

    Don't

    Conference room is available until 10 am

    When talking about a busy room, focus on the absolute time when it is next available. It is easier to plan ahead when you know what time a room will be free. It should answer the question "When can I come back?"

    Do

    Conference Room is booked until 3 pm

    Don't

    Conference Room is booked for 3 hours