I find that there’s still a lot of confusion in the community around where to find the most canonical and up to date documentation for Microsoft products. Fortunately for everyone other than Xamarin developers, the answer is straightforward now – just go to Microsoft Docs at docs.microsoft.com, not to be confused with docs.com which took a bullet to the temple just a few days ago.
The Docs platform is a constantly evolving and growing platform, and nothing like the staid and little updated documentation repositories of old – how though does it stay so up to date for platforms like Office 365 and Azure which can themselves update on almost a daily basis?
The answer, as with so many things these days, is community. All of the documentation in the Docs platform is hosted in GitHub, and all is available for anyone to submit changes to. Whenever you see a typo, or malformed code, or a cmdlet that’s changed, or something that’s just plain wrong, you can edit then and there yourself, and in so doing, contribute to the collective ongoing success of the IT community.
When confronted with GitHub though, many people I’ve shown this to have thrown up their hands and proclaimed ‘I can’t do that! That’s a developer tool! I’m an IT Pro!’ Well they’re wrong, and to show how simple it is to submit a change, we’re going to walk through an example right now.
Here we are, just ambling along happily reading the Azure Stack documentation to better understand how storage balancing works, and what our role as a Cloud Operator should be in proactively managing it, when shock! Horror! A mistake!
In the past and on other lesser document management platforms we would have scoffed and carried on, but the good digital citizen of the 21st century document management community won’t let this pass! He or she will take thirty seconds out of his or her day to ensure that no one else’s sensibilities are impinged by this literary travesty. Our good digital citizen cares about the application or service the documentation is about, and by extension cares about their fellow comrades in arms in the industry.
Onward now our plucky digital hero forges, and first clicks the ‘Edit’ button at the top right of the page.
Immediately a dark spell is cast! And we are transported in a whirl of sparks and smoke off-site to the Hub of the Gits, land of Sha1 and friends. It’s here in the Hub of Gits that we can actually lay our proposals for change at the feet of the mighty documentation owners, which is in no way meant to imply that the latter are in any way gits.
Before we venture forth, we must first have a name that the Sha1s and the Owners can know us by, for the nameless have no form and hence no power to effect change. The character creation screen is at the top right of the window, or if you already have an established character, simply sign in to sally forth your champion, and then ask why the hell you’re reading this guide if you already know how to use Git.
Your first unguided test here, adventurer, is to complete the sign up process, because to be honest if you can’t go through that unaided, then even setting this guide to “I’m Too Young to Die” would be too hard for you, and a Grue would very quickly gobble you up.
Ok fine, one hint.
There are various different ways that we could now propose our change to the Owners, however we’re speed running this and want to make sure we’re away from our actual task for as little time as possible. That being the case, we coax the crafty Edit button out of hiding, and give him a good hard click.
You’d think that the obvious thing now would be that you’d edit the page then and there, and submit it in place, but oh no! It is not to be! The Gods of Git are not so merciful, and thus drops your first piece of knowledge. In editing this document, a copy of the entire documentation repository has been created within your inventory screen! Much like the twists and turns in a path that any adventurer will encounter in their travels, this copy is called a Fork.
A strange message appears before you, and while some of the words now make sense, some are still completely alien to you.
The edit itself is painless and can be done in browser, and so with a deft sword stroke and a delete, the deed is done.
Our edit made, we simply scroll to the bottom of the page, enter a meaningful epitaph for our fallen foe, and click ‘Propose File Change’.
It’s at this point that we reach the ‘Are you sure you wish to continue, there is no turning back from this point’ screen, and it’s at this point that the majority of people in my experience back out. Stalwart adventurers though we are, we will forge on regardless and click that ‘Create pull request’ button!
So what is a Pull Request?
Quite simply, the changes you made to the file are in your local Fork of it, and you are requesting that the document owner Pulls your changes into their repository. I’ve had so many conversations that have started ‘Why isn’t it a push request! I’m pushing changes!’ No you’re not, you’re prostrating yourself before the Gods of Git and begging them to pull your changes into their One True Version, which will be displayed to all the world on docs.microsoft.com.
Now comes the actual real ‘This is your last chance to back out’ screen., but we’ve levelled up enough that we know what we’re doing, and fearlessly hit that final button to Create our Pull Request.
And that’s it! Your request will now go before the documentation owners, who will review and then commit or reject your changes.
Congratulations! Your quest is complete!
This is the path of the champion of documentation in the 21st century – a slight detour to a side-quest to help all those who come after them. As a bonus, every accepted change will see your character immortalised on that document as a contributor for all to see.
This is how documentation is maintained at the pace of Cloud, and it’s dependent on you to maintain that pace, so go forth and document! Unless you’re a Xamarin developer, then… I guess just wait until Xamarin documentation migrates to docs :/