Organize your page

These are some organization basics.

Organize your page 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 > All capabilities > All entities > (select an app or service). Select (user menu) > 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: Type the Email you use to sign in and to receive information from New Relic. 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 > All capabilities > APM & services > (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.

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 > All capabilities > APM & services > (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!

To learn the steps for basic docs, see Create and edit content.
To learn how to create and publish release notes, see Create release notes.
To make it even easier to start a new doc, use templates.