You can use this dictionary to guide your writing on docs.newrelic.com. We use this to help ensure consistency across our Docs site. Other than the terms listed here, we generally follow the Microsoft Style Guide, but we'll use Chicago Manual of Style in a pinch. We also follow American English conventions, rather than British English ones.
For a glossary of terminology specific to New Relic, see the public glossary on the Docs site.
Install the Ruby agent, not
Install the Ruby Agent.
Don't refer to a Synthetics
private minion as an
Use the 12-hour clock followed by the (lowercased) time period am or pm.
Don’t put a space after the last number in a timestamp (12:00am, not 12:00 am).
Don't include a leading 0 when the hour is less than 10.9:30am, 12:30pm, 8:30pm
Refer to the specific product, not just
- As a courtesy to your readers, on first mention always refer to Amazon products by their full names; for example Amazon Web Services (AWS). You can use the acronym after that, if there is one. Example:
Amazon Elastic Compute Cloud.
- After that, use the short name according to the AWS Documentation site. Example:
The "machine name" that the collector uses to uniquely identify an app is its
app name. The server-side configuration setting that changes the visible "name" of an app without changing its unique identifier is its
When using as a watermark or in the doc's title, use all caps:
Don't include a callout within the document unless the beta requires additional explanation. In the body text, use lowercase. For example:
<Callout variant="important">This feature currently is in private beta. To join the beta, contact your New Relic account rep.</Callout>
If the developer team prefers to use a term other than beta or private beta, clarify what is driving that use of the term (Legal requirement?), and add any relevant info here in the usage dictionary.
Use standard prefixes and capitalization for International System of Units (SI), International Organization for Standardization (ISO), or Joint Electron Device Engineering Council (JEDEC memory) values when referring to multiples of bits (b) and bytes (B). 1 byte = 8 bits.
For help with converting byte values (such as bytes to kilobytes), try this byte converter.
Don't use. Instead, use
deny list and
allow list; for example, "Add a hostname to your deny list."
In general, use
click rather than the vaguer
select. For example, you might click something in the UI, but then select something from a list.
Be particularly careful to use
click to describe actions that only make sense with a mouse; for example, with a
right-click or a
click and drag. Also use
click when the user must click on a non-selectable object (
to save your changes, click anywhere outside the dialog box). See also mouse over.
When referring to an agent talking to the New Relic servers, describe this as the New Relic collector. Although internally the
collector refers only to specific parts of our architecture, we use it more broadly in our documentation to mean "any endpoint a customer must connect to report data, for any product." Avoid "connect to New Relic," and do not use "connect to the New Relic UI."
When it makes sense for clarity, conciseness, and tone and voice, use contractions. Use them where they make the writing sound more like natural speech, and where they improve clarity and accessibility without sacrificing expertise and authority.
There are no hard and fast rules for which contractions are or aren't acceptable, but simple and common is preferable to complicated and rare. For example,
it is is fine, but less common constructions like
wouldn't've are best avoided.
- When using a negative contraction (
won't) try to provide some additional info about what what to do and what can be done. (See the style guide intro for more on this.)
- There are places in our docs—for example, in notes and warnings—where spelling out
will notis preferable to contractions to emphasize the action or blockage to be avoided.
Avoid referring to the document itself (the docs site page) as much as possible. If there's not a good alternative, you can use
documentation (whatever sounds most natural; try reading it aloud).
This document explains how to... or
For related docs, see...
dropdown instead of
Although it isn't common usage, you can use
dropdown independently as a noun, without needing to say
dropdown menu or
dropdown list. For example,
select a date from the <b>date</b> dropdown.
Don't use Latin abbreviations.
for example or
such as. Instead of
i.e. or its English equivalent
in other words, rewrite so your description is clear.
Em dashes are rarely needed in tech docs, sadly. You can usually accomplish what you need to by breaking the thought into multiple sentences or using parentheses. In some rare cases, though, an em dash can add drama and spice.
If you think you've found such a case, make sure you use them right. An em dash should always use the real em dash character (not a hyphen), and no space before and after. For example:
You can sign up for New Relic fast and free—we won't even ask for a credit card number.
You can insert an em dash with the
COMMAND+OPTION+- shortcut or use the HTML entity.
This is one word. Don't hyphenate.
When using an inline icon from the UI, always describe it first, then embed the icon image, and then end with the word
select the delete
Don't put icons in bold.
When writing about icons, describe the icon for its purpose or action, not what the icon looks like. For example:
Don't use, unless referring to the New Relic Infrastructure product.
Instead, use an appropriate substitute such as
Introduction to for overview docs for a particular product. For example,
Introduction to New Relic Infrastructure or
Introduction to the PHP agent or
Introduction to transaction traces.
Also avoid the
Thing: Tagline format, as in
X-Ray sessions: Traces and thread profiles for key transactions, unless having a title with keywords will help with SEO.
The proper name for Apple's desktop operating system is
Don't use the older product names
Mac OS X or
The primary account in a New Relic account with sub-accounts. Refer to a master's subordinate accounts as
For mouse movements that involve placing the mouse pointer over an area, but not clicking it. For example, the APM Overview page includes functions that are only visible when the mouse pointer is over a particular chart. Do not use
point to or
hover over. See also
Always refer to the agent and language as
.NET, never as
New Relic One isn't a product. It's a way to view New Relic data more easily, all in one place, and from multiple related accounts.
This has several implications for how we should refer to it:
Avoid phrasing that makes New Relic One sound like a separate product or a separate platform. There is a single New Relic platform through which our users interact with our products.
Avoid mentioning New Relic One where it can be avoided. For example, instead of saying "Use New Relic One workloads to...", you could instead say, "In New Relic, you can use workloads to..." and then in the doc explain where to find the feature. Another example: instead of referring to "The programmable New Relic One platform," we might say, "The New Relic platform is programmable: To start building, go to one.newrelic.com and..."
Do not use
nr1as an abbreviation of
New Relic One. The only reason to use
nr1is when referring to the
nr1package or library (for example: a reference to the command
In general, we want to avoid overloading our docs with "New Relic".
Always refer to the programming language as
NR ONLY for watermarking docs for internal consumption only (such as this style guide). Don't use
New Relic Only.
Use lower case for
open source. Some legal contracts may require upper case.
Don't use this outside of Browser docs. Often abbreviated as RUM, this is a generic industry term for Browser monitoring. New Relic refers to this as
page load timing (in Browser docs) or
New Relic Browser (in non-Browser docs). Within Browser docs, use this term only for SEO or clarification, never to refer to the actual feature.
report when discussing data sent to New Relic, such as, "your host reports data to New Relic."
Avoid using report as a noun. Instead use "the reported metrics" or "the collected data."
If "report" sounds too clunky, you can also use
collect as long as whatever New Relic is collecting doesn't sound security sensitive.
Don't refer to the New Relic UI as
RPM. Always refer to the specific product, such as the
APM UI or the
Browser UI. However, you may use
rpm when required in the visible URL string in UI paths.
Also referred to as an Oxford comma. Always use serial commas with inline lists. For example,
Portland, Seattle, and Dublin rather than
Portland, Seattle and Dublin.
Include a space (time zone). Don't hyphenate or run together as timezone.
update when users need to change the version of whatever they're using. No money or payment is needed for an update.
upgrade whenever money or payment may be involved, such as upgrading to the Pro version of a product. The new pricing model makes it unlikely that you'll need to use this.
One word (
username), not two. This is the most common usage and is recommended by Microsoft and Google style guides.
When referring to multiple version numbers, always use
or higher. Don't use
and higher, or the words
later. Also don't use punctuation, as in
version 1.2+. For example:
Foo requires Ruby agent version 1.2.3 or higher.
- Tell users to use the
latest versionand not an
- To abbreviate the word
version, use a lowercase
vwith no space before the number; for example,
upgradewhen talking about agent versions, as in "To update to the latest version..."
- For security reasons, do not use version numbers with licensing docs.
The Tech Docs team doesn't have a set standard when referring to previous versions. Recommendation:
- Consider using
version x.x or lowerwhen identifying a specific version.
- Consider using
In earlier agent versionswhen referring to versions more vaguely.
Say “we” and “our” when it works with the flow of your writing. Avoid overloading paragraphs with “New Relic” mentions, or reword so the focus is on the user, not New Relic. For example, avoid writing something like this:
New Relic recommends setting a startup timeout.
Instead, write something like this:
Recommendation: To help with troubleshooting, include a startup timeout in your configuration.
We recommend setting a startup timeout.
We use “you” and “your” liberally in our docs. Addressing the reader directly makes for simpler, cleaner sentences. It also tends to expose lazy uses of passive construction and it helps users to understand procedures.
However, avoid using generic “you” or “your” when permissions are involved, because we can't assume what permissions the user has.
For example, we can't just say “you can add and remove users from your account settings” when that is actually an Owner or Admin level capability. When permissions are relevant, use a permissions callout.