We publish our Azure Active Directory (Azure AD) documentation on docs.microsoft.com, which is our open source content publishing platform. We also allow you to change the content you read on docs.microsoft.com, so everyone can contribute content updates and changes. So, if ever see something in the docs that you’d like to change, just follow these steps:
1. Click Edit on the page you want to change.
When you’re on the page you want to change, click the Edit button in the upper right of the page above the main heading of the article.
The Edit button automatically takes you to the source file for the page on GitHub. Source files for Azure AD docs are kept in the azure-docs repo.
2. Sign in or sign up for GitHub.
You need to be signed in to GitHub before you can make any changes. If you don’t have an account on GitHub, you can set up one for free. Once you’re signed in you can edit any article published on docs.microsoft.com.
If you’re signed into GitHub, you can skip this step.
3. Edit the file in GitHub.
To edit the file on GitHub, click the pencil icon switch to edit mode.
You can now edit the file. Microsoft Docs uses Markdown, which is a simplified format for specifying basic HTML. To learn more about Markdown, see GitHub’s Mastering Markdown guide.
Make your changes in the Edit file tab in GitHub.
Click the Preview changes tab to see what your changes will look like when published. When you’re done making changes, scroll to the bottom of the page to the Propose file change section. Type a description of your change in the first box, and then click Propose file change.
Next, you’ll make a request to have your changes pulled into or merged with the main published content for Azure AD.
4. Submit a pull request.
A pull request in GitHub is how you notify us about your change. It’s a request to pull your changes into the main published content. After you have proposed your changes, GitHub automatically displays a page for creating your pull request. You can review your changes in the lower part of the page where your version and the current version are compared. If you’re happy with the changes you’ve made, click Create pull request.
On the Open a pull request page, click Create pull request again.
At this point, your pull request is submitted, and the author is automatically notified to review your changes.
If everything checks out, we’ll merge your changes, and your update will go live within a day or two. Keep an eye out for email notifications from GitHub for any clarifying questions from the author in the pull request comments. You’ll be notified by GitHub when your changes are merged.
That’s the process for making small simple changes. If you want to make more extensive changes, it’s best to set up a local clone of the repo on your computer and then push your changes to GitHub using Git or other tools with GitHub integration. Visual Studio Code has GitHub integration that makes working locally very easy. It’s free and is actually pretty cool.
To learn more about the basics of being a docs contributor, see the Microsoft Docs contributor guide. We always love to hear your feedback and suggestions, and we look forward to hearing from you! Let us know what you think in the comments below.
Alex Simons (@Alex_A_Simons )
Corporate VP of Program Management
Microsoft Identity Division