For consistency across New Relic content, here are our general word usage guidelines:
- We generally follow the Microsoft Style Guide, which is based on the Chicago Manual of Style.
- We follow American English conventions, rather than British English ones.
- We defer to the official product names for references to products. (For example, for Amazon Web Services (AWS), see aws.amazon.com/products.)
- For terminology specific to New Relic, we use the product glossary.
A unique number that identifies a particular New Relic account. Don't use account number
.
Don't capitalize. Install the Ruby agent
, not Install the Ruby Agent
.
Don't refer to a Synthetics private minion
as an agent
.
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 AWS
broadly.
- 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:
Amazon EC2
.
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 app alias
.
Use the beta callout. In the body text, use lowercase. For example:
BETA FEATURE
This feature is currently in beta.
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.
Decimal value | SI prefix | Binary value | ISO prefix | JEDEC prefix | |
---|---|---|---|---|---|
1000 | k: kilo | 1024 | Ki: kibi | K: kilo | |
1000^2 | M: mega | 1024^2 | Mi: mebi | M: mega | |
1000^3 | G: giga | 1024^3 | Gi: gibi | G: giga | |
1000^4 | T: tera | 1024^4 | Ti: tebi | --- | |
1000^5 | P: peta | 1024^5 | Pi: pebi | --- |
Tip
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."
This is more complex than can be covered in this usage dictionary. For detailed information, see:
A parent account contains one or more child accounts. Child accounts were previously referred to as "sub-accounts".
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]#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's
for it is
is fine, but less common constructions like mustn't
or wouldn't've
are best avoided.
Also:
- When using a negative contraction (
don't
,can't
,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
do not
,cannot
, orwill not
is preferable to contractions to emphasize the action or blockage to be avoided.
When possible, use the second person you
to form a sense of connection with the reader. For times when you need a descriptive third-person noun, keep the following guidelines in mind:
customer
anduser
are both appropriate depending on context.customer
makes more sense when talking about billing, or about a group of people or a business entity. For example, one customer may have one or more individual users who interact with New Relic through the customer's account(s).user
makes more sense as a general term for an individual user, or when talking about users as an object in the account model. For example, when discussing account models, it's important to be specific about what constitutes a single person identity in our system.
Don't use. Instead, use page
.
If you need to refer to the docs themselves—don't. Generally it's better to directly link to the doc you're referencing and use the doc title as your link text. For example, See [Install the .NET agent](URL)
rather than See our [.NET agent install docs](URL)
.
If there's not a good alternative, doc
generally sounds more natural than document
or documentation
. If you're tempted to use a longer form, try reading it aloud to see which reads best.
If you must refer to the site as a whole, call it the docs site
rather than Docs site
or documentation site
. Internally, you can also refer to the whole URL docs.newrelic.com
to avoid ambiguity with other sources of docs like internal platform docs or API explorer docs. To refer to our docs GitHub repo, use the repo name docs-website
or the repo path newrelic/docs-website
.
Use dropdown
instead of drop-down
or drop down
.
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.
Instead of e.g.
, use 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 icon
.
For example, select the delete
icon
.
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:
Yes: Select the edit icon.
No: Select the pencil icon.
For technical information on embedding images, see Inserting inline images and Embedding Font Awesome icons.
A list of entities, such as the APM applications index, the Synthetics Monitors index, or the Alerts Incidents index. See also page
.
Don't use, unless referring to the New Relic Infrastructure product.
Instead, use an appropriate substitute such as architecture
, environment
, system
, host
, etc.
Always use 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
.
Don't use welcome to
, basics
, intro
, overview
, etc.
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 macOS
.
Don't use the older product names Mac OS X
or OS X
.
We previously used "master account" and "sub-account" but now we use parent account and child account.
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 click
.
Always refer to the agent and language as .NET
, never as .Net
or .net
or dotnet
.
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
NR1
ornr1
as an abbreviation ofNew Relic One
. The only reason to usenr1
is when referring to thenr1
package or library (for example: a reference to the commandnr1 nerdpack:serve
).In general, we want to avoid overloading our docs with "New Relic".
For more details, see the New Relic One messaging guidelines, the docs glossary entry, or the New Relic One docs.
Always refer to the programming language as Node.js
, not Node
.
Use NR ONLY
for internal consumption only (such as this style guide). Don't use NR-ONLY
or NRONLY
or New Relic Only
.
See serial comma.
Use lower case for open source
. Some legal contracts may require upper case.
New Relic organizations can have a parent/child account structure. This is more important for our original user model but still plays a role for some behind-the-scenes features on our New Relic One user model. Learn more about account structure.
Parent accounts were previously referred to as master accounts, and there are still some uses of this in the codebase.
For pricing tier/edition language, see Pricing language.
See Pricing language.
Don't use this outside of browser monitoring docs. Often abbreviated as RUM, this is a generic industry term for browser monitoring. New Relic refers to this as page load timing
or browser monitoring
. Use this term only for SEO or clarification, not to refer to the actual feature.
Use 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.
If you need to tell a user how to path through the UI, see our style guide page on UI paths.
Use update
when users need to change the version of whatever they're using. No money or payment is needed for an update.
Use 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.
For styles and formats related to user roles and groups and more, see User-related style.
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 greater
or later
. Also don't use punctuation, as in version 1.2+
. For example:
Foo requires Ruby agent version 1.2.3 or higher.
In addition:
- Tell users to use the
latest version
and not anup-to-date
orcurrent
version. - To abbreviate the word
version
, use a lowercasev
with no space before the number; for example,v2
orv1.2.3
. - Use
update
notupgrade
when 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 lower
when identifying a specific version. - Consider using
In earlier agent versions
when 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.
OR
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.
For more help
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's and and documentation.