At Octopus Deploy, writing is one of the primary tools we use to share meaningful updates about our work and the problems we’re working to solve. This page includes guidelines to help give our written communications a consistent voice.
TL;DR:
- Use US English spelling.
- Use the active voice.
- Use plain language, conversational writing, and simple words and phrases over longer ones. Avoid slang and jargon.
- Write positively and warmly, like you’re talking to a customer face-to-face.
- Use sentence case for headings.
Why is a consistent voice important?
Everybody who works at Octopus has their own personality, focus, and quirks. But when we share updates with our customers and the wider world, we want those updates to feel like they’re coming from the same place and represent a common purpose.
We're a values-driven company, which sets us apart from many of our competitors. We're also all about making complex deployments simple. Our brand voice needs to reflect these things—our values, our empathy for our customers, and that we make things simpler. We want to sound down to earth, helpful, and trustworthy and use clear, friendly, straightforward language. We don't want to sound like our competitors. (So let's not "supercharge productivity with enhanced workflows!")
Having a consistent voice in our written communications is one way of conveying our shared goals as a company. With a well-defined voice, we can avoid customers scratching their heads because they don’t understand our colloquialisms, bad jokes, or out-of-date pop culture references.
Also, not everybody who interacts with Octopus Deploy or reads our words speaks English as their first language or has a degree in computer science, though many do. Our recommendations about voice and style help make our communication as widely accessible as possible.
What is the Octopus voice?
Voice in any piece of writing comes from the combination of specific word choices, the topic, and the worldview conveyed by the piece of writing.
The voice we’re striving for at Octopus conveys who we are, the problems we’re working to solve, how we think about those problems, and our attitude toward our industry and our customers.
The Octopus voice should demonstrate:
- Our domain expertise
- Our values
- Clarity of thought through concise and informative information
- Our willingness to help with respect, enthusiasm, and humility
- The benefit for our customers
- That we’re professional, approachable, helpful, and respectful, with an appropriate sense of humor
- That we’re direct, honest, and open
- That we’re thoughtful and opinionated but never condescending
- Be careful saying things like of course and obviously
- Use wording like we think this is helpful because or we hope you find this useful
- That we’re humble and not boastful, even when we’re celebrating
- That we’re genuine and empathetic
How do we achieve that?
- We don’t market at people; we communicate with them in a friendly, warm, and natural voice.
- We use the active voice to make our writing clear.
- We use plain English, always choosing simple words and sentences.
- We use a conversational style of writing, including contractions. For example, say Haven't instead of Have not. The more authentic, warm, and human you sound, the better the customer experience (this has been proven, even for dry institutions like hospitals, banks, and insurance companies). Don’t write something you wouldn’t say out loud.
- We don't use generated content (AI), for several reasons, including that it's verbose and not warm or natural. Octonauts can learn more about why we don't use generated content on our websites.
- We ask how our content helps our readers, what they need to know, and focus on the benefits, not the effort for our customers.
- We take our customers' needs seriously because we know their pains and how complicated software deployments can be.
- We’re honest and respectful.
- We consider the reader's state of mind and adjust our tone accordingly.
- We write in the positive. For example, This won’t take you more than 3 minutes becomes This will take you less than 3 minutes.
- Although we use humor and wit sometimes, we use them sparingly and in an inclusive way that shows we can relate to our customers’ experiences. We always choose clarity over humor, though.
- We use inclusive and gender-neutral language. Refer to Google’s word list and their documentation on inclusive writing for specific examples.
Octopus style
- Use US English spelling.
- Use plain English.
- Address the reader directly by writing in the second person. Imagine you are talking to the reader. To configure X, you need to do Y.
- Use simple sentence structures to avoid overloading the reader with too much information.
- Choose simple words and phrases over longer ones. For example, don’t say Due to the fact that say Because. Don’t say In order to just say To.
- Avoid formal language or an academic style, and use simple, declarative language.
- Avoid slang, colloquialisms, and other terms the reader might not be familiar with.
- Use modern language. Language evolves and terms fall out of use. Be deliberate about the language you choose. Where terms have changed, don’t cling to old terms just because.
- Use sentence case for titles and only capitalize words that are normally capitalized.
- Use the Oxford comma—a comma after the penultimate item in a list of 3 or more items, before and or or. For example, on-premises, cloud, and serverless.
- Define technical terms the reader might not know.
- Try to anticipate the problems your reader is trying to solve. In documentation, instead of describing features, explain how the feature can solve the user’s problem.
- When using bulleted lists:
- Start with a capital letter.
- If the list only contains fragments, don't punctuate.
- Punctuate full sentences only.
- Be consistent in each list (for example, use full sentences with punctuation for all points, or use fragments without punctuation for all points).
- Ensure each point flows on from the lead-in as a proper sentence if you’re using fragments.
- If you’re using an abbreviation or acronym and there’s a chance the reader won’t recognize it, spell it out the first time you mention it, with the abbreviation or acronym in brackets. Then use the short version for all other references.
- Avoid using exclamation marks, as they lose their impact when overused and can look unprofessional. Other than using one with Happy deployments! we use them sparingly. Default to not using them.
More on why we avoid AI-generated content when writing as Octopus
We don't use generated content (AI) on our websites or when we’re writing as Octopus in emails, newsletters, and other collateral. Reasons include that it's verbose, sounds off-brand and like our competitors, and sometimes makes subtle mistakes about our product that could erode trust if we publish them. We should use AI for the things it's good at, and writing isn't one of them. We also think AI-generated content can damage our site’s reputation in content quality assessments. Octonauts can learn more about our position on generated content on our websites.