Voice isn’t something you can apply to a piece of writing after the writing is complete, though editing, both self-editing and help from an editor, do help. For that reason, we structured this guidance to be useful as you work through the writing process from ideation to final draft.
Ideation
We want all our writing 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 it will benefit the reader.
Sometimes it’s helpful to write an exploratory draft to figure out exactly what you’re trying to say. Typically, though, 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:
- Octopus voice
- Why does voice matter
- Guidelines
That gave me the basic structure, and the rest grew from there.
First draft
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.
Structure
Structure your writing logically so 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 correct 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 understand your point. Don’t interrupt the text with a note that explains the 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’ve discussed.
Be direct and honest
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 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.
Be concise and informative
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 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.
Writing helpful explanations
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, making 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.
Think about the customer's pain and how we solve it
If you're talking about an Octopus feature, think about the customer's pain and how our feature solves that pain. Think about things from the customer's perspective so that you're telling their story, not ours. It can be helpful to use one of these formulas:
When you wanted to [do something], you used to have to [toil and pain]. But with our new [feature] you can [do something even better with less toil and pain].
or
It helps you do [X] without the [Y/pain].
Editing
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. During editing, make sure:
- You've expressed your ideas in an easy-to-understand way
- The writing is as clear as possible
- The writing tone hits the right notes
Cut, cut, and then cut some more
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.
Less is almost always more
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 unnecessary words to help the reader understand your point.
If you can delete something without altering the meaning or tone of the text, delete it.
Don’t repeat yourself
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.
Word order
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 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.
Focus on word choice
As you read your draft, try to remember the reader only has the words you put on the screen. 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 "be verbing". For example: I’ll be showing you becomes I show you.
Remove unnecessary command words. For example: Click on Settings becomes Click Settings, and Open up the browser becomes Open the browser.
Don’t be overly formal or too casual
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.
Use conversational language because people find it friendly, trustworthy, and straightforward. Studies show that people find formal writing dull, intimidating, and less trustworthy.
However, avoid slang and being too colloquial. Even though Octopus is based in Australia, we avoid Aussie colloquialisms because most of our audience isn’t Australian and probably doesn’t know the difference between a doona and an esky.
Conclusion
Following these tips will help create text that’s focused on the reader’s problem and keep the tone we’re using consistent.