Use the following style guide to ensure the Terra documentation is understandable, useful, consistent, and organized.
Although the current Terra 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.
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.
Use natural language, like a person. Always assume Terra users are not experts, and simplify the content while maintaining technical accuracy. Avoid technical jargon.
Always consider Terra 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.
Provide relevant content without being wordy. Avoid repeating details in a single topic.
Use the same terminology, formatting, voice, and tone.
Write in a personable voice with a positive attitude.
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.
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 Terra users.
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.
Remember the two primary types of Terra users: new and experienced.
Use them. They're part of writing like a person.
Use sentence-style capitalization in all levels of headings.
Use the present tense and active voice. Address the audience as you.