Microsoft has gone significantly above and beyond, in my opinion at least, with the new documentation platform at https://docs.microsoft.com. At first I figured it might be a refresh of the same old same old, providing a channel for product teams and others at Microsoft to push information out to the community and their customers… allowing us to comment and hope for the best in terms of upkeep and corrections.

I have been using https://docs.microsoft.com for a while now, primarily in the consumption sense and I no longer feel this is the case.

What is different about Docs?

Microsoft has taken some of their software (I’m looking at you .Net Core and PowerShell) open source. The source code has been pushed to GitHub and is available for community contributions, comments, and usage. This same approach was used for documentation.

The documentation is also hosted on GitHub at https://github.com/Microsoft-Docs making it possible for the community to contribute, edit, update, and suggest things. This is a huge turn around from the Microsoft of old – giving way to an open organization with a bigger customer focus.

Note: I am not here to debate the customer focused-ness of the new Microsoft. They are not perfect, but neither am I and the things I have seen from them as of late are a big step in the right direction.

Why should I care?

The documentation of Microsoft’s products and services is Microsoft’s problem… why do I as a consumer of their products give an extra thought to this? Simple. You and I are the consumers and evangelists for Microsoft’s products. We use them every day and are helping our customers by helping their customers. If I find something in their documentation that doesn’t quite work as it should, I no longer have to wait until some documentation developer or product team person gets around to the comment on the doc to look at it – remember this happened like once upon a not very often in days gone by.

Now I can simply edit the document and be taken over to GitHub and change it. Once I have made changes, they get submitted and the original author (and any other contributors) are notified of the edit. From here – discussion with the original author and others begins. Once everyone is in agreement, the changes are “merged”.Depending on the documentation you have edited, the publication (the thing that shows up on https://docs.microsoft.com) happens twice per day.Once your merged edits are published they appear in the real live documentation.

Remember – you can edit these works, but so can others and that is completely awesome. We as technology professionals do not know it all, and we should not be expected to. Helping each other out makes all of us better.

How do I get started?

To begin your journey into editing documentation for Microsoft you will need a free GitHub account – visit https://github.com/join?source=header-home to create one. Then you will want to review the open source code of conduct –



From there please read the style guide and guidelines for contribution:
– https://docs.microsoft.com/en-us/contribute/contribute/style-quick-start
– https://docs.microsoft.com/en-us/contribute/

Whew.Now that all of that reading is out of the way you can dive right in to contributing. To do so, the best way to get started is to find the documentation you wish to change and click the Edit button right on the top right of the website – shown below

Figure A

Editing Microsoft’s live documentation

Do my changes just go live? Holy cow.

They do not – your contribution is tagged with appropriate labels and are triaged by the documentation team(s) and others at Microsoft (and in the community). There can be back and forth discussion about the changes you are proposing as well.

Once the hurdles have been cleared the changes will likely be merged and appear shortly thereafter in the documentation.

What about questions or feedback?

Microsoft is working to get all of the comments in the https://docs.microsoft.com system to use GitHub issues as the backend – this way comments and questions are tracked just like edits to documents – this also keeps things moving and very visible in the community. Not all things are handled this way just yet, but this is coming and will be a very good thing. It helps keep everyone in the loop on an issue, which is good for all sides.

If you have questions or feedback, when someone at Microsoft or in the community sees and assigns your item you will be notified. That is how Issues work – they keep everyone in the loop.

Figure B

An issue filed for an update

I think Microsoft has made a great decision in moving https://docs.microsoft.com to open source and relying on the community. This makes the documentation better, helps make the people at Microsoft working on documentation and features better, and makes improves community engagement on Microsoft’s products. Knowing that I can fix something that just isn’t quite right or needs a ton of work is pretty awesome and quite a vast improvement from past Microsoft.

It’s simple really – if you see something, and have an idea how to fix it, jump in and help fix it – the Microsoft community will be better for it. Create a GitHub account and give it a shot the community is here to help, please join us in helping Microsoft better its documentation for the betterment of all of us.