Standard Docs Style guide

Use the following style guide to ensure the Standard documentation is understandable, useful, consistent, and organized. This style guide is a fork from Osmosis.

Although the current Standard documentation doesn't adhere to all of the following style guidelines, apply them when you revise the current content and write new content. Over time, the style guidelines will be applied throughout the documentation.

Basic principles

The following principles guide our content creation.

• Write clearly and accurately.
• Be aware of your audience.
• Get to the point.
• Be consistent.
• Be friendly.
• Include everyone.

Write clearly and accurately

Use natural language, like a person. Always assume Standard users are not experts, and simplify the content while maintaining technical accuracy. Avoid technical jargon.

Be aware of your audience

Always consider Standard users' needs and help them complete processes quickly and easily. Do this by including all steps in procedures, suggesting best practices, and including tips and other types of notes.

Get to the point

Provide relevant content without being wordy. Avoid repeating details in a single topic.

Be consistent

Use the same terminology, formatting, voice, and tone.

Be friendly

Write in a personable voice with a positive attitude.

Include everyone

All people are welcome here. Use appropriate language as it relates to matters of identity.

For more information, see the Microsoft bias-free writing guidelines.

Style guidelines

Generally, we abide by the Microsoft Writing Style Guide because it shares our goal of creating clear and useful content. However, we don't follow every rule, and, in some cases, we break the rules in favor of our own.

Here are some of the more important guidelines we use. If you follow at least these guidelines, your content will begin to resemble other parts of the documentation, making a consistent experience for Standard users.

Acronyms

Use the spelled-out term followed by the acronym in parentheses, such as dynamic-link library (DLL). On subsequent occurrences in the same topic, use only the acronym.

Audience knowledge levels

Remember the two primary types of Standard users: new and experienced.

Contractions

Use them. They're part of writing like a person.

Sentence case

Use sentence-style capitalization in all levels of headings.

Verb tense

Use the present tense and active voice. Address the audience as you.