General Guidelines

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:

Address people as people

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.

Deliver the message directly and simply but keep it engaging

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.

Be friendly and warm but not overly familiar

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”:

• You can begin sentences with conjunctions
• You can use sentence fragments when it clarifies the message
• You can end sentences with prepositions to avoid awkward sentences
• You do not need to spell out the number 1-8 when they appear within a sentence (If a number starts a sentence spell it out, otherwise just use the numerical representation. Five vs 5)

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.

Be knowledgeable

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.