Compartilhar via

Contributing to Microsoft Azure documentation

  • Artigo

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

Comments

  • Anonymous
    July 18, 2016
    Very useful! Great post Ken!
    • Anonymous
      July 18, 2016
      Thanks, Chervine! I quite enjoy the whole Git editing process Microsoft has put in place for their documents. It makes it a real community effort.
    • Anonymous
      July 18, 2016
      Thanks, Chervine. I find the whole process flow for edits on articles very intuitive. It makes contributing to the community super easy.
  • Anonymous
    July 19, 2016
    Really great post Ken. Thanks
    • Anonymous
      July 19, 2016
      Thanks, Chilberto.
  • Anonymous
    July 20, 2016
    Thanks Ken! I think this is also cool because they can determine if they want to accept each pull request. Obviously, most would come from folks like you who genuinely want to improve the articles. Thanks!
    • Anonymous
      July 20, 2016
      Thanks, Ed. And yes - the pull request system is more labour intensive for the reviewers but it ensures a higher quality document in the end.
  • Anonymous
    February 08, 2017
    Thanks Ken! This is what I was looking for to help me contribute to the Azure documentation. You saved me a lot of time.
    • Anonymous
      February 08, 2017
      You are welcome Arlan. Glad it helped!