• EnglishEspañol日本語한국어Português
  • EntrarComeçar agora

Voice strategies for docs that sound like us

First, some definitions

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. We have voice traits that we aspire to: honest, empowering, and ingenious. Here’s where you can learn more about how we write that voice.

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 honest, empowering, and ingenious voice in your sights. These guidelines can help.

Why voice and tone matter

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:

  • Honest, empowering, and ingenious
  • A pleasure to read and use
  • Accessible for busy people

Know your audience

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

Strategies for being honest, empowering, and ingenious

Here’s a quick guide to writing our voice traits:

Trait

It means

It feels

But not

Honest

You can trust us to say what really happens, and back up statements with data.

Truthful, authentic, transparent, frank, approachable

Abrupt, boastful, complicated, curt, chatty, arrogant

Empowering

We understand what you’re trying to do, and we’re here to help you cut through the gaps, guesses, assumptions, and opinions and get back to creating, launching, and running great software.

Uplifting, inspiring, optimistic, supportive

Arrogant, presumptuous, overconfident, pushy

Ingenious

We’re insatiably curious, endlessly fascinated, and ready to solve problems from any angle. We make the conditions for breakthroughs. It is our superpower.

Smart, intuitive, innovative, magical, intellectually bold

Know-it-all, trendy, miraculous, aggressive

Consider reading aloud to hear how your content sounds. Is it natural? Are the sentences punchy and encouraging? Great! Then think about how you can bring in some other strategies as well.

Get creative

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.

Examples

What not to do

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.

Other New Relic voice and tone resources

The following were used in the making of the above guidelines, and can broaden your perspective:

  • The fifth Q on content that’s honest, empowering, and ingenious.
  • The UI writing guidelines almost all apply to our docs as well as product strings.
  • The marketing brand guidelines describe the difference between voice and tone, and how we achieve the New Relic voice of honest, empowering, and ingenious. You can find a link to these if you’re a New Relic employee by going to the word-nerds Slack channel.
Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.