Writing for QuickBooks is like having a conversation with a friend. We know all the basic grammar rules (and even some obscure ones), but we’re not sticklers. When in doubt, pick the conventions of everyday conversation over the grammar book.
- Write in active voice
- Favor simple tenses
- Aim for 5th-8th grade readability
- Be precise and definitive if you can
- Be accessible to everyone
- Use everyday contractions
- End sentences with prepositions
- Don’t overuse exclamations
- Use similes and metaphors when it’s appropriate
- Describe things before using the technical terms for them
Write in active voice
It’s typically clearer, more direct, and easier to read than passive voice. And it’s almost always shorter.
Every now and again, it’ll sound better to put the focus on an object and omit the thing doing the action. This is the rare exception when passive voice is OK.
Feeling lost? Here’s the deal: With active voice, the subject performs the action of the verb, usually on an object. (Think: she designed the screen.) With passive voice, the subject receives the action of the verb. (Think: the screen was designed by her.) Passive sentences are longer than active ones because they usually need a helping verb like “is” or “was” to make sense. Passive voice is the hallmark of bureaucratic jargon, evasion, and skirting responsibility. Don’t use it.
End sentences with prepositions—most of the time
It’s fine to end sentences with prepositions. We prefer it, in fact. Just be careful not to slip into something that’s too informal. If you’d never say it in conversation, then don’t write it that way.
Favor simple tenses
For the most part, write in simple tenses—past, present, and future—because they’re direct, clear, and short. Sometimes they make sense for the situation and sound natural, but often they they just add extra words unnecessarily. Be mindful of that and have rationale when you use them. It’s fine to use But try to stay away from progressive tenses unless you need to convey ongoing action.
Know why else you should write using simple tenses? They’re easier for non-native speakers to understand and for translation teams to translate.
Don’t overuse exclamations
Show your enthusiasm with exclamations. Just make sure they sound like a natural reaction to the situation. They work best with single words and short phrases. Don’t ever use a double (!!) or triple (!!!) exclamation. If you’re that excited, use visual supplements like color, illustrations, and motion to amplify the excitement. And don’t use two or three exclamatory words in a row.
Use first person for QuickBooks
Use “we,” “our,” and “us” when you write as QuickBooks. It’s one way that we make experiences feel more personal. We want customers to know that there are people behind QuickBooks and that we’re in this with them. Just don’t be creepy. We never want them to think we’re spying on them. Exception: when you’re referring to the actual product, especially in Marketing and Sales, use “it,” not “us.”
Be precise and definitive as possible
Customers look to us for answers and guidance. So when you explain things, be as definitive and precise as you can. There will be times, of course, when you don’t know exactly what’s going on. That’s a good opportunity for you to push your partners to improve the experience so you can speak more directly to what’s happening. But if all else fails and you have to be vague, still try to be as straightforward as possible.
Use second person for customers, except for buttons and legal stuff
Our product experiences are a conversation with customers. We talk directly to them, so use second person to address them. Buttons are the exception, though. They represent the customer’s side of the conversation, so it’s OK to use first person there to represent the customer’s voice and maintain the conversational quality of our writing. Note that first person in buttons is an option, not a mandate.
Describe things before using the technical terms for them
As much as we’d like to, we can’t just stop using the language of accounting, finance, and technology. Customers will need to talk to accountants, lenders, and other finance people, and those people are bound to use terms like deduction, liability, Profit and Loss, and so on. We want to empower them with knowledge, not make them feel defeated by speaking a different language and assuming fluency.
As the proactive champion of our customers, you’re their filter, so be a good judge of what terms they need to know. If they need to know something, describe it in a simple way first, then give it a name. After that, use the term and maybe include a reminder.
Use third person for people who aren’t the customer, and keep things gender neutral
Use third person when you refer to someone (or something) other than the customer performing the action.
And try to keep things gender neutral, including pronouns. If you find yourself in the awkward spot where the subject’s gender is unknown, write your way around it. Don’t use “she/he,” “s/he,” “they” or “them,” or “one.” If you absolutely can’t write your way around it, then it’s OK to use they, them, or their.
There are other ways to be gender neutral and as inclusive as possible:
- Instead of “ladies and gentlemen,” use something like “distinguished guests” or be more specific and say “customers” or “developers.”
- Instead of “men” or “women,” use “everyone.”
- Instead of “the lady or man in the green shirt,” say “the person in the green shirt.”
- Instead of “guys,” try “folks” or “friends” or “team.” These are all better choices in communications such as Slack messages.
- Instead of “boys and girls,” simply say “children.”
- Instead of “brothers and sisters,” try “siblings.”
These neutral choices might not be possible in other languages, but try to be as inclusive as possible when you can.
Use similes and metaphors when it’s appropriate
A metaphor puts one thing in terms of another. A simile does it by using “like” or “as” to make the comparison. They’re useful when you want to explain something technical or difficult in terms that are more friendly and approachable. Feel free to use metaphors anywhere you have the room to explain something. Just be careful with these. What sounds good to you may not resonate with others.
Use everyday contractions
Use the contractions of everyday conversation. Just don’t get carried away. We don’t use regional contractions like “ain’t”, “shan’t”, “y’all” (sorry, Texas), “mustn’t”, and so on. Here’s a list of contractions that are usually fine:
Don’t turn nouns into contractions. And beware: Contractions get tricky when it comes to translation. Work with your regional content designers to decide how to handle them.
Aim for 5th-8th grade readability
You can test your content using readability tools to get an idea of the grade level or years of education someone needs to understand it.
Our target range is 5th to 8th grade. This might feel low—we know that accounting and finances are inherently complex. But these lower grade levels help our users comprehend the content faster and more easily. And they support our usage guidelines on writing shorter sentences, using simple tenses, and choosing familiar words.
They can also make localization and translation easier. Even more, they benefit our US users for whom English is a second language. (Over 20% of US residents don’t speak English at home.)
When scoring content, the most useful numbers to look at are the Flesch-Kincaid Grade Level and the Gunning Fog Index. The Flesch Reading Ease score is also interesting—a high number (close to 100) is better than a low number.
Be accessible to everyone
Some of our users can’t see. They use screen readers when doing things on the web. Someone can tell a screen reader to only read headings (h1, h2, etc.), or to skip from section to section, or just from link to link.
We use descriptive alt text for images, icons, and controls. If it’s text meant to be read, we don’t put it in an image.
We don’t refer to where things physically appear on a screen.
We write meaningful link text. Long text links can be partially hidden in the code for people using screen readers.
We create text alternatives for charts and graphs. A cool way to do this is to include a data table near the chart.
Some of our users are color blind. Others have low vision and needs lots of contrast between background and text. Some people use screen magnifiers, and others just prefer to zoom or enlarge text to make things easier to read.
Include icons with text to make things clear. And don’t use images of text. It’s not screen-reader-friendly, and this type of text can’t be enlarged when someone zooms in on the screen.
Some of our users can’t hear. They need to be able to read text versions of voice-overs or recordings.
Some of our users have cognitive impairments or learning disabilities. These folks need content that is simple, clear, and direct, to help focus their attention.