Skip to content

Commit

Permalink
fix(style guide): moved docs-centric info from first page to a separa…
Browse files Browse the repository at this point in the history 
…te page
  • Loading branch information
@mmfred
mmfred committed Nov 8, 2021
1 parent edc4012 commit 3832f0f
Show file tree
Hide file tree
Showing 3 changed files with 233 additions and 220 deletions.
219 changes: 0 additions & 219 deletions src/content/docs/style-guide/get-started/introduction-style-guide.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,223 +29,4 @@ Welcome to New Relic's style guide. We've written these guidelines for content c
This guide also gives you some insight into how we think about good technical writing. We focus on style and usage that's particular to New Relic. We follow American English conventions. For topics that aren't covered, please refer to the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) (for guidelines on technical terminology) or the [Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html) (for general writing and editing guidelines).


## Organize your doc to make it easier to read [#organization]

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.

<table>
<thead>
<tr>
<th width={200}>
**How to organize information**
</th>

<th>
**Comments**
</th>
</tr>
</thead>

<tbody>
<tr>
<td>
Separate **what** and **why** from **how**.
</td>

<td>
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.
</td>
</tr>

<tr>
<td>
Front-load directions with context.
</td>

<td>
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](https://one.newrelic.com) > Explorer > (select an app or service).**
* Select **[(account dropdown)](/docs/accounts-partnerships/education/getting-started-new-relic/glossary#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."
</td>
</tr>

<tr>
<td>
Separate requirements from options.
</td>

<td>
**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.
</td>
</tr>

<tr>
<td>
Follow the "five to nine" guideline.
</td>

<td>
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.
</td>
</tr>
</tbody>
</table>

Other organization tools to consider:

* [Levels of headings](/docs/style-guide/writing-guidelines/levels-headings)
* [Lists](/docs/style-guide/quick-reference/lists)
* [Collapsers](/docs/style-guide/quick-reference/collapsers)
* [Callouts](/docs/style-guide/quick-reference/callouts)
* [Tables](/docs/style-guide/quick-reference/tables)
* [Code examples](/docs/style-guide/quick-reference/code-examples)
* [**For more help** section](/docs/style-guide/writing-guidelines/more-help-section)

## Use action-oriented titles [#action-oriented-titles]

Wherever possible, give your document or [h2 heading](/docs/style-guide/writing-guidelines/levels-headings) 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.

<table>
<thead>
<tr>
<th width={80}>
Quality
</th>

<th>
Title example
</th>
</tr>
</thead>

<tbody>
<tr>
<td>
Bad
</td>

<td>
The query history
</td>
</tr>

<tr>
<td>
Okay
</td>

<td>
View query history
</td>
</tr>

<tr>
<td>
Good
</td>

<td>
[Query history: Create and edit NRQL queries](/docs/query-your-data/nrql-new-relic-query-language/get-started/introduction-nrql-new-relics-query-language)
</td>
</tr>
</tbody>
</table>

## Start the document with an introductory paragraph [#intro]

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 [#doc_length]

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](#categories).

## Use the New Relic voice [#voice]

We strive for a voice that's approachable, expert, and visionary. Check out our [voice guidelines](docs/style-guide/writing-guidelines/voice-strategies-docs-sound-new-relic/) for how to write content with these qualities. And keep in mind these essential writing tips that apply to any type of documentation.

<table>
<thead>
<tr>
<th width={200}>
**Guidelines**
</th>

<th>
**Comments**
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Be clear and direct.
</td>

<td>
Remember to:

* Use present tense.
* [Use active voice; avoid passive voice.](http://www.yourdictionary.com/index.php/pdf/articles/43.activevspassivevoice.pdf)
* 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](https://one.newrelic.com) > APM > (select an app or service) > Settings > Application**.
</td>
</tr>

<tr>
<td>
Write to aid localization and translation.
</td>

<td>
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.
</td>
</tr>
</tbody>
</table>

## Change doc titles and anchors [#titles]

Because changes to doc titles, anchors, and redirects can break links to other docs, please [create an issue](https://github.com/newrelic/docs-website/issues/new/choose) to request these types of changes and we'll help you out with that.

## Create and edit categories [#categories]

Because changes to categories can affect large groups of docs at once, please [create an issue](https://github.com/newrelic/docs-website/issues/new/choose) to request these types of changes and we'll help you out with that.

## Start writing and editing docs [#start]

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

* To learn the steps for basic docs, see [Create and edit content](/docs/style-guide/writing-guidelines/create-edit-content).
* To learn how to create and publish release notes, see [Create release notes](/docs/style-guide/writing-guidelines/create-release-notes).
* To make it even easier to start a new doc, use [templates](/docs/style-guide/article-templates).

0 comments on commit 3832f0f

Please sign in to comment.