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).
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:
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
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.
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.
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.
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.
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.
You are ready to start writing and editing New Relic docs!