Writing guidelines
Our goal when we speak is to be the perfect sidekick to our listener. We do this by:
Knowing our audience
Using plain language
Minding voice, tone, and style
Writing accessibly
Where to use this
Follow these guidelines when your writing will be “coming from” CBRE Build, the company. Here are some examples:
UI copywriting, emails, and notifications
Marketing sites and print material
Social media
Communication with the rest of CBRE
Documentation
Start using these guidelines, and you might find they apply to your personal communication as well.
Introduction
As technologists, it can be easy to forget that one of our most powerful, precise, and flexible tools is writing. Software is mainly text. Take the words away, and most screens become useless. Writing is part of the design, and deserves our best thinking.
Knowing our audience
The people we write for are busy. They have jobs to do, and our products and posts are not their priority. But that’s ok — we just need to make the most of the moments when we have their attention. Our role is to be Alfred, not Batman.
So be prepared. Know as much as you can before you speak. How does this moment factor into your listener’s job? What state of mind has the last moment left them in? Can we use what they already know to be better understood, to provide context, or to save time?
The better you understand your listener, the better they’ll understand what you say.
Using plain language
Communications transmitted by and received at many organizations, be they digital, paper-based, or mobile, are often lacking in important prerequisites for comprehension. This problem has often been exacerbated by solution deprioritization or poor awareness at the executive level. Failure to determine the cause, and ultimately nonaction, are realities for many organizations. Cross-functional productivity, personnel morale, and even key workforce retention metrics are traditionally affected, and in many cases penalties are drawn on institutional monies. But solutions are near at hand, and these have historically proven satisfactory in the augmentation of comprehension, especially among non-executive groups.
Do you follow? Of course not. This reads like some broadcast issued from a vast system that has never known empathy. We cannot sense the warmth of a person inside, or who they might be speaking to, let alone what they are saying. No one talks this way. If they did, they’d quickly lose our attention.
Instead of sounding important, but leaving you to extract the meaning, I could have worked harder to be clear. I could have said that many companies’ writing is confusing, and their leaders do not notice the problem; that it affects the businesses by draining first their souls, then their morale, people, and money; and that a proven solution is available.
That solution is plain language. Plain language is a way of thinking. It’s permission to relax and be conversational. It’s an understanding that basic words do not indicate a simple mind. And it’s a commitment to clarity, which means working a little harder at thinking before we speak.
The principles of plain language are clarity, simplicity, brevity, and warmth.
Use them to measure everything you write. Make sure every word is pulling its weight.
Avoid turning verbs into nouns.
Words that end in -tion are warning signs. Instead of “Better results were achieved through utilization of the button,” say “People who used the button had better results.”
Do not use long words when short ones will do.
Buy instead of purchase, help instead of assist, use instead of utilize, about instead of approximately… see this list for more.
Avoid jargon, acronyms, and cliches.
When we use words people understand, our writing is more accessible, searchable, and inclusive. Jargon carries a risk of being misinterpreted or sounding officious. If there’s really only one name for something, like a technical term from your user’s vocabulary, it’s fine to use it. Just be careful, and make sure to define it the first time you use it with a nontechnical reader.
Be specific.
Avoid meaningless generalizations, which tend to obscure good stories. Watch out for words like “enhanced” or “enabled” or “improved”. In what way, exactly, is it better?
Instead of “enhancements to app loading,” say “Loading is now about 40% faster for people with spotty connections.”
If you’re having trouble writing in plain language, step back and imagine you’re having a one-on-one conversation with your reader. You are ready to help. Whatever you’d say is a great place to start.
Minding voice, tone, and style
Blocks helps us be consistent with our visual language. It teaches the people who use our products what to expect when we interact, and it gives them a sense of who we are. Our written language can do the same if we are careful with our voice, style, and tone.
Voice is our personality. Tone is the way we express it within a certain context. Style is the choices we make about what we say.
Voice
When we speak as a company, it might be through a product, through email, social media, notifications or anything else. We might talk to the people who use our software, to recruits, to the rest of CBRE, or to our own team. But in all these cases, the voice should be uniquely and consistently ours: the voice of the perfect sidekick.
The perfect sidekick is a step ahead, but never in the way. They keep things light, but are never unprofessional. They’re serious about the mission. They know their partner’s minds. Unprompted, they expertly provide just the thing for the moment.
The perfect sidekick’s voice is:
Straightforward, conversational, and prepared
Expert, but not pompous
Genuine and grounded
Honest and human
Upbeat but not cloying
More informative than expressive
Wry, but never inappropriate
Silent when necessary
Tone
You only have one voice, but you use it differently in different situations. That breadth of usage is tone.
When speaking for CBRE Build, use what you know about your listener to match your message to their moment. If they’ve completed something big, help them celebrate; if they’re waiting, reassure them; if it’s appropriate, throw in a joke; if something’s gone wrong, be upfront and offer a fix.
The way we talk about CBRE provides a good example. When speaking to the company, it’s helpful to be specific: we’re “the world’s biggest commercial real estate services firm by revenue.” But when speaking to Builders, or potential Builders, the specificity might sound unfriendly. Knowing our audience, who might already be skeptical of real estate, we sense that being casual is better: “The biggest commercial real estate company.”
When you play with tone, be a little careful not to go too far. Our voice is informal, but not casual, and entertainment should never come at the cost of clarity. Know your audience, and tone will come naturally. The exuberant tone we use on Build recruiting materials is probably not appropriate for our usual, busy people. A playful error message might work for a job applicant who needs reassurance, but would be inappropriate for software used in front of a client. It’s ok to have fun with it, but if you’re uncertain about tone, err on the side of neutrality.
Style
Style comes from choices we make about how we speak. Our choices reflect our values of warmth, clarity, and inclusion.
Use the active voice
People think in stories, and passive voice obscures the roles and the action. The first paragraph of the Plain Language section is so turgid because when we read it, we cannot visualize anyone doing anything.
In the active voice, a subject does something to an object: “We released the app.”
In the passive voice, the object has something done to it, often by a mysterious entity: “The app was released.”
Use short words. And short sentences.
They’re easier for everyone to understand. Air around the words invites us in, assuring us that a courteous human being is speaking.
Look at the first and third paragraphs of the Plain Language section. Even without reading, we see that the first is knotty, treacherous territory. The third looks lighter, familiar, like speech.
But vary your sentence length to sound natural.
Short sentences are useful. They make their point. And they march forward. But too many is boring. All ears want variety.
Give your readers a healthy mix of short, medium, and long sentences. It’ll keep their attention and keep them happy.
Break up long sentences and long paragraphs.
If a sentence has fewer than 14 words, readers understand 90% of the content. At 25 words, sentences are much harder to figure out.
Address the reader in implied second person.
If possible, avoid pronouns in the UI. However, if a personal pronoun makes possession clearer, remember you’re having a conversation with the reader, so the UI should say “Your” instead of “My.”
Do not let caveats, exceptions, or minor details dictate unwieldy grammar.
“You can” rather than “You may be able to”. Use approximate numbers if it’s helpful. Note the discrepancy elsewhere if you must. The third paragraph in Tone above is another example.
Write positively.
Instead of “You cannot start a project because you have no properties selected,” say “Select a property to start a project.”
Do not be redundant — it’s disrespectful of your reader’s time.
Avoid repeating information, especially information that is already present in headers or labels. Instead, use structure to create meaning and take words off the page.
Use contractions.
They’re helpful and friendly. But be careful of negative contractions (more below).
Writing accessibly
We want everyone to understand what we write — even those who have to work harder at language, seeing, or hearing. Every word added to a page weighs down the brain on its climb to comprehension. Tired brains give up. And most people only read 20–30% of the text on a web page anyway.
Write for skimming.
Structure your content with headings and lists, and put the most important information first.
Do not use ALL CAPS.
It's harder to read, and we do not yell at our readers.
Do not use negative contractions.
They’re easy to mistake for their positive counterparts, especially when skimming.
Use gender neutral pronouns.
If you know your subject’s pronouns, use them.
Resources and recommendations
Credit to these sources, which were all really helpful in writing this. If you want to learn more, these are good trailheads.