• /
  • Log in

Introduction to the style guide

We've written these guidelines to make it easier for you to contribute to our docs, as well as to give you some insight into how we think about good technical writing. We, the Tech Docs team, rely on your expertise to keep New Relic's documentation updated and useful. Thank you for your willingness to share your knowledge!

Our style guide focuses on style and usage that's particular to our site. Our site follows American English conventions. For topics that aren't covered, please refer to the Microsoft Writing Style Guide (for guidelines on technical terminology) or the Chicago Manual of Style (for general writing and editing guidelines).

Organize your doc to make it easier to read

Consider these organization guidelines when thinking about the order of information in a doc. By following these guidelines, you'll make it easier for readers to skim and find what they need.

How to organize information

Comments

Separate what and why from how.

Define any necessary prerequisites, policies, or background information (the what and the why) before you step through the how (step-by-step procedures).

Examples:

  • Explain what the feature is and why it matters before telling readers how to use it.
  • Describe any limitations with user permissions or subscription levels that would prevent them from using the feature. If the feature is available for any user or subscription level, don't bother to say so.
  • Provide a roadmap for what users will be able to accomplish, so they know before starting a procedure that they have everything they need.

Front-load directions with context.

Make sure readers know where they need to be, before telling them what to do. In general, use (select an app) to describe what users select from the product index.

Examples:

  • Go to one.newrelic.com > Explorer > (select an app or service).

  • Select (account dropdown) > User preferences.

  • On the command line, type gitk.

    Also, structure steps by front-loading context from the user's point of view. For example, instead of "Go to x to do y," structure the step as "To do y, go to x."

Separate requirements from options.

Example:

  1. Type the Email you use to sign in and to receive information from New Relic.
  2. Optional: Type additional user emails, separated by commas.

Follow the "five to nine" guideline.

Depending on the topic, organize the information so there is a maximum of five to nine chunks of information. For example, readers may start to get lost or overwhelmed after about five h2 sections or seven steps into a procedure.

If you have more than nine h2 sections or steps, you might need to create an additional doc or procedure.

Other organization tools to consider:

Use action-oriented titles

Wherever possible, give your document or h2 heading a task- or action-oriented title. Focus on what users are trying to accomplish or the problem they're trying to solve. Use present-tense verbs, rather than "-ing" verbs.

Quality

Title example

Bad

The query history

Okay

View query history

Good

Query history: Create and edit NRQL queries

Start the document with an introductory paragraph

Unless the document is less than a single screen in length, begin with a brief paragraph that introduces the topic or summarizes the important points.

Not sure where to start? Try writing all the content for your document first, and then add the introduction to the top to summarize your key points. Or use the introduction to expand on the text in your metaDescription in the metadata.

Keep documents short

The amount of content needed can help you decide whether you need one or more documents for the topic.

  • If all of the document's contents apply directly to the title, then everything belongs in the same document.
  • If several related sections could be logically split into individual documents, and the overall length of your document is more than about two screenfuls, split those sections into other documents. Be sure to include links to the related contents.
  • If a large document needs to be broken into multiple smaller documents, consider whether they might be best grouped together in their own sub-category.

Use the New Relic voice

We strive for a voice that's approachable, expert, and visionary. Check out our voice guidelines for how to write content with these qualities. And keep in mind these essential writing tips that apply to any type of documentation.

Guidelines

Comments

Be clear and direct.

Remember to:

  • Use present tense.

  • Use active voice; avoid passive voice.

  • Tell users what to do, not what they "should" do.

  • If absolutely necessary, tell users what not to do in situations where unexpected results may occur. Whenever possible, provide an alternative suggestion when telling users what not to do.

    Example: Using active voice with an alternative suggestion for what not to do

    Do not use your config file to change this setting, because this could affect other processes. Instead, go to one.newrelic.com > APM > (select an app or service) > Settings > Application.

Write to aid localization and translation.

Do not use euphemisms, idioms, jargon, or slang. Use the same terms and wording consistently. If you need to include an abbreviation or acronym, spell it out the first time it appears in the document.

Always take a moment to ask yourself whether people will really understand the terms you are using in the way you're using them.

Change doc titles and anchors

Because changes to doc titles, anchors, and redirects can break links to other docs, please create an issue to request these types of changes and we'll help you out with that.

Create and edit categories

Because changes to categories can affect large groups of docs at once, please create an issue to request these types of changes and we'll help you out with that.

Start writing and editing docs

You are ready to start writing and editing New Relic docs!

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.