When your learning a new technology, like Azure, documentation is key and find inaccurate, out of date or just plain wrong documentation is incredibly frustrating. Microsoft have taken an interesting approach to this issue by storing all Azure (and many other MS services) documentation sources on Github and allowing the community to submit pull requests. What this means is that if you spot an error in a document or you feel it needs updating you can make this change your self and get the document updated very quickly, rather than waiting for product teams to spot the issue and make corrections. The process is very easy and doesn’t require any working knowledge of Git.

Submitting a documentation pull request

To request a change to a document you are first going to need to sign up for a Github account, it’s free and takes a few seconds to setup.

Once you have your account locate the documentation page for which you want to submit the change. On this page, usually in the top right you will find some links for feedback, edit and share:

Select the edit link, this will take you to this pages Github entry. This shows the content of the page, in MarkDown format. Along the top of the document you will see a number of options, one of which is the pencil icon, click this to start editing the document.

This will then change the document into edit mode, and you can go ahead and edit the document directly in the browser. Any formatting you require should be done in Markdown, if your not familiar with this take a look at this document.

Once you’ve made all your changes, scroll down to the bottom of the document and you’ll see a box with a title of “Propose file change”. In here enter the details of your change and when you are ready click “Propose File Change”

When you hit this button it will create a Pull Request for you, if your not familiar with Git this is a request that documents the changes you made, along with your comments and passes them to the project owners to review and approve or decline. Once they are approved they will get merged into the existing document and your change will go live.

The pull request will show you what you have changed in the doucument so you can check that this is what you intended.

Once your happy with this change click the “Create Pull Request” button.

Once you do that, your request will be created, the owners notified and the status of the request changed to “Change sent to Author”. You can keep up to date with the status of your request on this page, and view any comments that are added. The approvers may come back and ask for clarification or additional changes, but if everything is in order they will approve your request and the Pull Request will be merged.

Congratulations, your change is now live on the Azure documents site.

Licence Considerations

If your change is relatively minor then it is covered by the docs.microsoft.com terms of use and doesn’t require anything further, however if you are making a more substantial change then this may require you agreeing to the Contribution Licence Agreement. If this is the case a request to agree to this will appear in your pull request and won’t progress until you agree to it.