Best practices for writing/publishing content to Docs.Microsoft.Com

This guide is designed to provide tips and best practices for Docs.Microsoft.Com contributors, enabling them to publish quality content, on time.

Hitting your publish date

The tips below will help you avoid last-minute frenzy, and get your content published on time. This is especially important when content is required to align with a product/service release on a specific date.

  1. Author your article in Markdown (*.md) from day one—do not use Word to write your article.

    Why: You avoid the time required to convert from Word to Markdown, as well as the additional vector for introducing errors when you perform the conversion.

  2. Use the major or long-running changes workflow, and create a pull request (PR) for your article on day one. Regularly push your changes to GitHub so that you can review it on staging as you go.

    Why: You can see the rendering of your article on docs.microsoft.com, and receive error notifications from the automated builds. This helps you avoid last-minute fixes required by the PR reviewers, and get things like broken links fixed well before sign-off.

  3. Use GitHub's built-in pull request review feature to perform your article review with your team members and the content team.

    Why #1: It's a slick, built-in feature of GitHub, and allows you to track all requested changes (on even a line-by-line basis) from multiple reviewers.

    Why #2: Your article is already in Markdown, on GitHub, and staged on docs.microsoft.com, so you—and your reviewers—can review the article as it will appear when it's published live.

    Why #3: You aren't authoring in Word anymore, and you need a replacement for Word's review feature.

  4. C+E/APEX contributors should start the PR review process early, and #sign-off on your article at least 2 days before your target publish date.

    Why: This gives you plenty of time to integrate any changes required by the PR Reviewers team (this is when they kick back your article and issue a #hold-off comment). Rarely are articles approved on the first try, even for those on the content team. You must give yourself time to fix and resubmit the article for review via #sign-off well before your target publish date. A resubmitted article does not get placed at the top of the review queue, so you have to wait in line with everyone else.

Additional resources