Style and voice quick start

This quick start will require minimal time, but give you a good idea of how to apply the most important Docs style concepts when writing articles for docs.microsoft.com. These guidelines apply whether you are creating new documentation or updating existing documentation.

At a bare minimum, please:

  • Spell check and grammar check your topics, even if you have to cut and paste into Word to do it.
  • Use a casual and friendly voice--like you were talking to another person one-on-one.
  • Use simple sentences. They are easier to understand, and they are more easily translated by both human and machine translators.

Use the Microsoft voice principles

We aspire to follow these principles when we write technical content for docs.microsoft.com. We may not always get there, but we need to keep trying!

  • Focus on the intent: Customers have a specific purpose in mind when they consult our documentation. Before you begin writing, clearly determine who the customer is and what task he or she is trying to do. Then, write your article to help that specific customer do that specific task.

  • Use everyday words: Try to use natural language, the words your customers use; be less formal but not less technical; provide examples that explain new concepts.

  • Write concisely: Don't waste words and don't over explain. Be affirmative and don't use extra words or lots of qualifiers. Keep sentences short and concise. Keep your topic focused. If a task has a qualifier, put it at the beginning of the sentence or paragraph. Also, keep the number of notes to a minimum. Use a screenshot when it can save words.

  • Make your article easy to scan: Put the most important things first. Use sections to chunk long procedures into more manageable groups of steps (procedures with more than 12 steps are probably too long). Use a screenshot when it adds clarity.

  • Show empathy: Use a supportive tone in the article, and keep disclaimers to a minimum. Honestly call out areas that will be frustrating to customers. Make sure the article focuses on what matters to the customer, don't just give a technical lecture.

Here's a handy reference that provides a summary of the voice principles, and can serve as a job aid for implementing them. Jump to the Self-paced voice training videos for details on how to integrate the voice principles into your writing.

Consider localization and machine translation

Our technical articles are translated into several languages, and some are modified for particular markets or geographies. People might also be using machine translation on the web to read the technical articles. So, keep the following guidelines in mind when writing:

  • Make sure the article contains no grammar, spelling, or punctuation errors: This is something we should do in general. Some Markdown editors such as Markdown Pad 2.0 have a basic spell checker, but it is a good practice to paste the (rendered HTML) content from the article into Word, which has a more robust spell and grammar checker.

  • Make your sentences as short as possible: Compound sentences or chains of clauses make translation difficult. Split up sentences if you can do it without being too redundant or sounding weird. We don't really want articles written in unnatural language either.

  • Use simple and consistent sentence construction: Consistency is better for translation. Avoid parentheticals and asides, and have the subject as near the beginning of the sentence as possible. Check out a few published topics - if a topic has a friendly, easy to read style, use it as a model.

  • Use consistent wording and capitalization: Again, consistency is key. We use sentence casing for titles, so do not capitalize a word if it isn't at the start of a sentence or a proper noun.

  • Include the "small words": Words that we consider small and unimportant in English because they are understood for context (such as "a", "the", "that", and "is") are crucial for machine translation - make sure you include them.

Other style and voice issues to watch for

  • Don't break up steps with commentary or asides.

  • For steps that include code snippets, put additional information about the step into the code as comments. This reduces the amount of text people have to read through, and the key information gets copied into the code project to remind people of what the code is doing when they refer to it later.

  • Use official product/service names, such as “Microsoft Intune” or "Microsoft Advanced Threat Analytics". Or you can just say “Intune” or "Advanced Threat Analytics".

  • Don’t create acronyms in place of official product names, especially if they are not already established. For instance, don't use "Azure MS" in place of "Azure Mobile Services", or "AAD" in place of "Azure Active Directory". If an acronym is already established, such as "AD" spell it out on first reference with the acronym in parentheses ("Azure Active Directory (AD)"), then use "Azure AD" for subsequent references. Try to avoid acronyms in general though - they just confuse people.

  • Use sentence casing for all titles.

  • Use "sign-in" and not "log-in."

  • Include the words "following" or "as follows" in every sentence that precedes a list or code snippet.

Localized documentation

Next steps

  • For the complete style and voice reference, please review the Docs style guide