A consistent, strong voice and tone establishes a positive relationship with our customers. Through sales, marketing, and onboarding people grow to expect Bronto to be warm, accessible, a little quirky, and relaxed. To continue this relationship in our UI text and technical documentation engineering writing should:
Use first and second person. Refer to our customer as you - never refer to customers as customers in externally facing documentation. Our customers’ customers should be referred to as contacts. When talking about Bronto don’t use terminology like company or corporation. When referencing the company use Bronto or we and use Bronto or the platform when referencing the product.
Simple and direct does not mean dumbing things down. Instead, strive for clarity through sentence structure and word choice. Avoid using jargon and overly-complicated or verbose language. Generally, use active voice in order to promote clarity. Longer sentences are OK when necessary, but read the sentence aloud to make sure it makes sense.
Direct and simple language does not have to be dry. Remember to keep your tone conversational. A conversational tone of voice helps to build trust. When you read what you’ve written it should sound similar to how you would talk to someone if you were having a conversation.
Informal grammar helps to convey friendliness. For example, use contractions in your writing. While we shouldn’t promote sloppy writing, adhering too strictly to grammar rules can make documentation uncomfortably formal. Some rules it is ok to “break”:
A certain amount of humor also promotes friendliness, but keep it light and use it sparingly. Humor is often individually subjective so never use it in a situation where it can lead to confusion or be interpreted as rude or offensive.
Avoid using qualifying terms like “we believe” or “we think”. Engineering is expected to be experts and we should present a clear, strong message in all of our writing.