Contributing to Microsoft Azure documentation

Most people know that Microsoft has embraced open source initiatives by sharing their code through GitHub. However, not only their code exists on GitHub but also their documentation.

While reading the documentation for Microsoft Azure, ASP.NET, Visual Studio Code, or Microsoft Edge you will often see an invitation to “Edit on GitHub”. Clicking this link will take you to the source article in the project’s public GitHub repository.

GitHub01

In this post, I will talk about editing docs on GitHub and how you can get started too.

My Experience

For the past few weeks, I have been contributing edits to Azure docs through my GitHub account. The editing process is fairly simple and can be accomplished by even the most novice of GitHub users. Changing an article will create a Pull Request on GitHub that notifies the original author edits are waiting for review. The author can either accept or reject your contributions. Pull requests are typically responded to within 48 hours.

Since starting I have submitted three edits and all have been accepted. To see a typical pull request I submit, view this commit. Click the Commit tab and then the commit ID to see the whole changeset.

GitHub02

How To Make Text-Only Edits In GitHub

If you would like to contribute, the following steps detail making text-only changes to existing Microsoft Azure articles in GitHub. These changes rarely require you to sign a Contribution License Agreement (CLA). For original articles or large edits to existing posts, a CLA may be required. The Azure Pull Request Bot will automatically check each submission to see if a CLA is warranted. For more information, see the Microsoft Azure Technical Documentation Contributor Guide.

  1. Visit the article you want to review and update.
  2. Click the Edit on GitHub link at the top of the article.
  3. Sign in to GitHub.
  4. In the GitHub version of the article, click the edit icon to fork the project so it can be modified. Subsequent edits to the same project will all use the same forked repo.GitHub03
  5. Make changes to the file and then review them for accuracy.
  6. Once complete, enter a descriptive summary of your changes and click Propose file change.
  7. A Pull Request will be created. You will receive an email about your pull request. Subsequent emails will notify you if your change has been accepted or not.

Summary

I encourage everyone to submit improvements to Microsoft documentation on GitHub. It makes the docs stronger and you are actively contributing to the open source community.If you have already submitted changes to Microsoft Azure documentation through GitHub then please share your experiences in a comment below.

See Also