Voice strategies for docs that sound like New Relic
Approachable, expert, visionary. That’s how we describe the New Relic voice. That doesn’t mean that our execs will sound like the UI or that the UI will sound like the docs. But they should all sound like they come from the same approachable, expert, and visionary company.
So what does that mean for our content? Read on!
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.
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.
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:
approachable, expert, and visionary
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 approachable, expert, and visionary
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.
The fastest, easiest way to eradicate robot voice: contractions.
Do
Don't
Here's how you can quickly build a "Hello, World!" application in New Relic One.
When you select an attribute you've set up for facet filtering, it filters the current dashboard.
The following steps show you how to build a “Hello, World!” application in New Relic One.
When you select an attribute you have set up for facet filtering, it filters the current dashboard.
Almost always speak directly to readers and use “you.” Just about never talk about “the user” or “the customer.”
Do
Don't
If you’re not a New Relic customer yet, you can create a free account.
You don’t have to understand the underlying data structure to use most of our features.
If a user is not a New Relic customer, they can create a free account.
Customers can use most of our features without needing to understand the underlying data structure.
Avoid starting with New Relic, or a product or feature name. Emphasize what the user can solve or the value they’ll gain with a feature or product. This puts their needs and interests at the front and center.
Do
Don't
Monitor dispersed microservices by connecting your logs with the rest of your data.
Collect, explore, and alert on all your metrics, events, logs, and traces from any source. Answer any question in milliseconds with our open, unified platform.
New Relic offers a fast, scalable log management platform that allows you to connect your logs with the rest of your telemetry and infrastructure data.
New Relic’s Telemetry Data Platform provides the world’s most powerful managed, open and unified platform for collecting, exploring, and alerting on your metrics, events, logs, and traces.
Lead with a verb to give your sentences energy and emphasize what your readers will be able to do with the product. Compare the examples in the previous section for the effect of this small shift. (Use this one as appropriate. If every sentence on a page starts with a verb, that page might feel a bit pushy and relentless.)
There’s a reason we built a “Why it matters” section into the intro template. Telling readers why something matters helps them make decisions and get the most out of our products: does the feature solve the problem they’re trying to solve, are there ways to use the feature that they hadn’t considered before? Also, it saves them time.
Example (from the Logs docs)
Bringing all of this data together in a single tool allows you to quickly get to the root cause of an issue and find the log lines that you need to identify and resolve a problem.
We walk a tough line with our content. We want to appeal to all users, including those who have a lot of experience in the concepts and terms we use. But new users might not know our jargon, acronyms, or even concepts. You can't define every term -- you'd never get through a sentence. But define key terms, and as always, put yourself in the reader's shoes.
Do
Don't
Monitor your websites, critical business transactions, and API endpoints with Synthetic monitoring. Synthetic monitoring is a handful of tools that simulate user traffic so you can proactively detect and fix outages and poor performance. Before your customers notice.
Monitor your websites, critical business transactions, and API endpoints with Synthetic monitoring.
There's a difference between implying meaning and stating it. The explicit version tells a reader what to look for in their Apdex score. The implicit version makes readers figure that out on their own. We often hear that our customers want opinionated docs. This is an example.
Explicit
Implicit
Apdex rates user satisfaction with your app (from 0–1) based on response times.
The more responses stay near your target time (currently 0.5 seconds), and the fewer errors you have, the higher your score. The closer your score is to 1, the better your app is performing.
Your app’s Apdex T-value is set to 0.5 seconds. That means requests responding in less than 0.5 seconds are satisfying(s), responding between 0.5 seconds and 2.0 seconds are tolerating (t), and responding in more than 2.0 seconds are frustrating (f).
Key transactions contribute to the overall Apdex score based on their own Apdex T-values.
Get readers to the info they need as quickly as possible. Make your pages attractive and approachable at the same time. It’s easy: just cut the cruft.
At the phrase level
Cut out UI elements when they’re not necessary to convey meaning. For example, no need to say “Click the Enter button” when you can just say, “Click Enter.”
At the sentence level
Look at sentences for things that might be roboting them up. Are there noun pile-ups? Are you naming every last thing to the point of wordiness and confusion?
At the page level
Make pages scannable. Include plenty of white space.
break things up with headings and lists
chunk sections down into clamshells
cut repetition
make sure it's all very skimmable
Eradicate the junk drawer. If your page is full of warnings, caveats, and lots of callouts before you even get to the good stuff -- the point of the page -- then restructure. Maybe allocate the cautions and need to know items to their own section. This feels less haphazard and inspires more confidence.
Avoid overstuffing. Focus. If a page is too long, and maybe there are paragraphs on paragraphs of information, it’s probably trying to do too much. Give it a read for content that’s not on topic. Get ruthless about removing unnecessary detail. Consider splitting the page.
Don't patronize or suggest something's easy, but do encourage. For example, if you're working through a complex procedure, you might drop in some encouraging milestones. Like, "If you run this query and data is reported, that's great! It means everything is configured and running properly."
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
Envision your data as a complex system of roads: you need to navigate the signs and signals along the way to quickly see and make meaning of the information you collect. New Relic One dashboards gather and chart the specific data you want to see, the way you want to see it, from anywhere in the New Relic platform.
HTTP headers act like passports on an international trip: They identify your software traces and carry important information as they travel through various networks, processes, and security systems.
At New Relic, we're super proud of NRDB, the New Relic database where we store your data. It gathers all your telemetry data in one place, gives you a connected view of all your data, and scales as your business grows.
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 approachable, expert and visionary.
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.