At Octopus Deploy, the written word is one of the primary tools we use to share meaningful updates about the work we do and the problems we’re working to solve. This page includes guidelines to help give our written communications a consistent voice.
We’re more than 200 people working across different functions at Octopus Deploy. We all have our own personalities, focuses, 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 that they represent a common purpose.
Having a consistent voice in our written communications is one way of conveying our shared goals as a company, and with a well-defined voice, we can avoid leaving customers scratching their heads because they don’t understand our colloquialisms, bad jokes, or out-of-date pop culture references.
Voice in any piece of writing comes from the combination of specific word choices, the topic being written about, and the world view conveyed by the piece of writing.
The voice we’re striving for at Octopus is intended to convey 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:
Voice isn’t something that can be applied to a piece of writing after the writing has been completed, though editing, both self-editing and help from an editor, do help. For that reason, this guidance is structured to be useful as you work through the writing process from ideation to final draft.
We want every piece of writing we produce to be useful to the intended audience.
After reading something we’ve written, we want our readers to feel like they benefited in some way. The better we define our topic before we start writing, the greater the chances are it will be beneficial to the reader.
Sometimes it’s helpful to write an exploratory draft to figure out exactly what you’re trying to say, but typically, knowing what you want to say and the problem you’re solving before you start will result in a piece of writing with a well-defined topic that’s useful to the audience.
For this page, I considered the problem and any questions the reader might have, and I wrote these notes before I started:
That gave me the basic structure, and the rest grew from there.
The first draft is where your ideas take shape. Not everybody works the same way, but these are some of the things to consider as you work.
Your writing should be structured in a logical order so that it’s easy for the reader to understand your message.
Introduction. Argument. Conclusion.
As you write, remember the order that ideas occur to you isn’t necessarily the right order to present those ideas to the reader.
If you’re exploring a complex technical idea, you might realize there’s additional information the reader needs to know in order to understand your current point. Don’t interrupt the text with a note that explains that prerequisite knowledge. Go back through the text to find the most helpful place to add this information so that the reader already has it when they need it.
Similarly, some authors write their introduction last when they already know what they’re going to talk about.
Our users are educated professionals who prefer directness and honesty so they can decide for themselves if something is useful or interesting. They’re (rightly) suspicious of anything that sounds like marketing-speak, and they generally want to know the details. We don’t use hyperbole or try to hoodwink people into reading on. We don’t hide behind fuzzy marketing terms or pretend we’re experts in something if we’re not.
Tell it how it is, and if you need to provide context, provide it.
There’s some tension between being concise and being informative, but the tension is there to help us find a happy medium. Depending on the topic, a 4,000 word blog post can still be concise if cutting sections from the post would leave the reader with an incomplete picture.
Some ideas take longer to explain than others.
At the same time, explaining all the edge cases of a specific scenario, just in case, can leave a piece of writing feeling bloated and not very useful. Consider the primary use case of the audience and focus on giving them all the information they need to achieve their goal.
When you’re trying to explain something to readers, consider your explanation from their perspective.
When you’re an expert at something, it’s hard to remember what it was like before you became an expert, which makes it easy to gloss over details. Try to recall the steps you took as you learned about the thing you’re explaining, that progression from not knowing to knowing might provide the model you need to explain the concept to the reader.
Alternatively, consider the problem the reader is trying to solve and write your explanation tailored to their problem.
From the ideation and drafting process, you should now have a well thought out piece of writing that follows a logical structure and presents information in a clear(ish) way. The editing phase is where you make sure your ideas are expressed in an easy to understand way, the writing is as clear as possible, and that the tone of the writing hits the right notes.
Delete anything that doesn’t reinforce the point you’re trying to make.
Start big and work your way down. Does every section provide useful information that is necessary to make your point? Delete any points that are merely nice to have, or add more details so that instead of just taking up space, every point provides useful information.
Do the same thing with each sentence. If you find sentences that are pleasing to you but don’t add anything useful for the reader, delete them.
The more unnecessary content you cut, the sharper the finished piece of writing will be.
Sentences are the building blocks of writing. Each sentence needs to add something useful and build on the sentences before it.
Because the topics we write about are often complicated, it helps the reader if we use simple sentence structures and keep them as lean as possible.
For instance:
Try to remove as many of the unnecessary words as possible to help the reader understand what you’re trying to say.
This makes sense, but we can convey the same point with fewer words, which means less work for the reader.
Remove any unnecessary words to help the reader understand your point.
If something can be deleted without altering the meaning or tone of the text, delete it.
It’s common to make the same point multiple times in a first draft as you find better ways of expressing your idea. Remove the less effective sentence.
Avoid repetition or saying the same thing twice in a different way unless you’re doing it to reinforce a point.
Think about sentence structure and word order, for instance:
Select option A from the User Preferences screen after you’ve logged into the portal.
This example presents the information in the wrong order. Option A is the ultimate goal and so perhaps the most important thing, but the sentence should be changed to guide the user through the process they need to follow without having to read the sentence backward:
Log into the portal, click the User Preferences screen, and select option A.
As you read your draft, try to remember the reader only has the words you put on the screen. That is, they don’t know what you’re trying to say, only what you said; avoiding ambiguity and being as specific as possible helps the reader understand exactly what you’re trying to say.
If you’re writing a technical blog post that walks users through multiple steps to achieve a goal, be as specific as you can; for example, don’t say set it up and leave the reader to wonder which it you’re referring to. Give them specific directions; for instance, configure the connection.
Provide details that reassure the reader they’re doing exactly what they need to do.
Using the most specific words and phrases will sometimes make sentences longer, but that’s okay, the goal isn’t to have the shortest piece of text possible, it’s to convey your meaning in the most effective way.
Avoid academic language, and use the words you normally use (not utilize) when you’re talking. If you’d feel silly saying something in conversation, don’t write it down.
Similarly, avoid being too casual.
Even though Octopus is based in Australia, we’ve made a conscious decision to avoid Aussie colloquialisms because most of our audience isn’t Australian and probably doesn’t know the difference between a doona and an esky.
Following these tips will help create text that’s focused on the reader’s problem and keep the tone we’re using consistent.