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
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).
Front-load directions with context.
Make sure readers know where they need to be, before telling them what to do. In general, use
Separate requirements from options.
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.
The query history
View query history
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.
Be clear and direct.
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!