Voice is how we talk to people. It’s influenced by things like tone, style, personality, and substance and is almost always consistent across all kinds of content.
Tone is the mood or atmosphere that’s created. You shift your tone depending on whether you’re writing something serious, like security information, versus introducing a new feature that you want to encourage users to try out.
Regardless of the tone you use, always keep that approachable, expert, visionary voice in your sights. These guidelines can help.
Voice and tone enhance our relationship with customers. We want readers to feel like they’re learning from a really smart friend. Not the show-offy kind, but the kind who really wants you to get it and is great at explaining things. That way, our content becomes:
- approachable, expert, and visionary
- a pleasure to read and use
- accessible for busy people
Through our docs, we’re constantly taking into account our DevOps audience. We design information to help these readers learn and solve problems. Attention to voice, particularly voice that appeals to developers, ensures that they want to keep reading.
Who they are: obviously, everyone is different. In general, developers want tools that work and info that’s delivered quickly and then gets out of the way. And some fizzy water. They like fizzy water.
Writing for developers means:
- clean, clear, human writing
- content that’s short and on topic
- a light seasoning of developer-y jargon is good (make sure context keeps things clear)
- no corporate speak or BS
- dropping in some interesting verbs - futz or grok, for example
We already do many of these. Keep on addressing the reader as “you.” Keep on using common contractions. Keep on writing crisp, clear content that cuts out the clutter.
Consider reading aloud to hear how your content sounds. Does it sound natural? Are the sentences punchy and encouraging? Great! Then think about how you can lay out some other strategies as well.
To take things a step further, consider pushing the voice. Add an analogy or metaphor. Metaphors are helpful for explaining complex ideas and the data shows that engineers use them a lot. Get a little creative with language. Inject a use case with a little more detail. You can even humble brag about New Relic products in a way that’s fun and obviously tongue in cheek. If you’re working with an SME, enlist their help in coming up with particularly apt analogies.
Intros and overview pages are a great place for pushing voice a little more:
- Readers are in the right mindset for something a little unusual (unusual for tech writing that is—we’re not saying go full James Joyce or Doctor Suess here). These readers are looking to learn about a product or feature, rather than solve an urgent problem.
- These are sometimes the reader's first impressions of the docs and the products. If they’re engaged, they’re likely to keep reading, and will get to know our products better.
- A little goes a long way. One or two voice-y sentences at the top of the page sets the tone, even if the rest of the page is strictly business.
While there are lots of things to do to achieve the New Relic voice, there are a few things to avoid as well:
- Don’t be pointless. Inject some fun or creativity, but don’t waste the reader’s time. An extended metaphor or a lengthy story about the user’s favorite taco stand can quickly try their patience. We’re talking brushstrokes, not paragraphs.
- Don’t push too hard. Check in on what feels natural and comfortable. If you feel awkward writing it, your content will likely read as pretty awkward as well.
- Don’t bring in memes or trendy internet slogans. They’ll go out of style quickly, might date the content, and will eventually be a general turnoff.
- Don’t write for a North American audience only. Doing so makes it harder to translate our docs, and isn’t inclusive to those outside of North America who are reading the docs in English. This means avoid references to sports like baseball and American football, or TV shows popular in the US. It might also mean to avoid US landmarks, history, etc.
- Avoid ableist language. Terms like "crazy" or "dumb" or "blind" might seem innocuous, but are not.
- Don’t be controversial. Don't alienate customers.
The following were used in the making of the above guidelines, and can broaden your perspective:
- The fifth Q on content that’s approachable, expert and visionary.
- This 10 tips for user-friendly writing (internal New Relic) slide deck quickly, succinctly captures main points for voice.
- The UI writing guidelines (internal New Relic) almost all apply to our docs as well as product strings. (Note: you need to be on VPN to see these)
- The marketing brand guidelines (internal New Relic) describe the difference between voice and tone, and how we achieve the New Relic voice of approachable, expert, and visionary, presented in terms of marketing copy.