The Joy of Making Simple Edits to Microsoft's Docs

When working on the previous blog post, I spent some time at microsoft's documentation site, where I noticed a small error: two similar articles had their titles swapped with each other. As in: Foo had Bar's title and Bar had Foo's title.

Usually you see an error like this and just move on.

But the edit button caught my eye, and I decided to try fixing the mistake. I was pretty apprehensive because these kind of things so often lead to yak shaving, and my current schedule does not permit the shaving of yaks.

So I clicked 'edit'. This took me to a github repo containing the source file, written in markdown. Hey, I write everything in markdown these days, so this looked promising. I backed up and soon found a page describing how to contribute.

Reading the description there, a tiny bug fix like this doesn't require too much work.

I "forked" the repository:

...and then cloned the fork of the repository onto my local machine, with:

git clone https://github.com/secretGeek/Docs.git

UPDATE: There is a much simpler way to do this, that avoids the need to press 'fork', or to clone onto your local machine. It is detailed at the end of this article in a P.S.

I found the files that need to be corrected, made the correction, and then committed the changes locally:

git add *
git commit . -m "title of iis.md and iis-with-msdeploy were back-to-front."

Double checked that the changes I'd made were the right ones, by inspecting them again...

git diff --cached

Then pushed the changes back to github, so that my online forked version of the repository was correct.

git push

At github, in my fork of the repository, I clicked on 'New pull request' which led me to a page where I could see how my fork differed from the original repo. I reviewed the changes once more, then clicked the 'Create pull request' button. I wrote a brief description of my change and then sent it into The Ether by clicking the first green button I saw.

Off it went. Wheeeeee! My pedantry, embodied in digital form, zipping around the globe.

Back in the original repository I saw a fleet of bots spring to life, checking and analyzing everything that was happening. One of the bots noticed I was a first time contributor, and asked me to digitally sign a contribution license agreement. It even gave this helpful guarantee "I promise there's no faxing" which was a nice touch.

I was then whisked expertly through a DocuSign process where I gave a website enough details about me that they could prepare the paperwork for this contribution license. It arrived in my inbox a minute later. I signed what I needed to sign, digitally, and was amazed that some team of people, somewhere in the world, had designed this well enough for legal hoops to be jumped in mere moments. This sort of baloney would've eaten up a week, easily, not too many years ago.

While I was busy doing the signing, the bots were hard at work verifying everything else, and I noticed from other emails that the bots were now happy, and had decided to forward my pull request onto their human masters.

I felt oddly nervous at this point. Battle scars from years of forum administrators shouting that a question has just been asked in the wrong forum, or from bureaucrats rejecting work because form 27B is not filled out in triplicate... a knot formed in my stomach as I prepared for a tiny little rejection, of this tiny little contrib.

Shortly thereafter there was a kind response from the original author, who was happy with the contribution, and the deal was done.

It was a good feeling, good enough that I felt inspired to write about it, at a time when I do not have time for writing about things.

You know me: I usually just take pot-shots at microsoft from afar, and have plenty of fun doing it. But now, this increasingly open microsoft lets me make positive contributions instead. And having done it once, it will be easier in future.

I hope that this extremely detailed walkthrough will inspire you to consider making a tiny contribution to an open source project for yourself.

(As usual, let me know the bits I did in a silly way, so others can learn.)

(Threw this together, including historically accurate screenshots, in 15 minutes, thanks to TimeSnapper)

P.S. There's also a simpler way that avoids the need to clone onto your local drive...

My book "Choose Your First Product" is available now.

It gives you 4 easy steps to find and validate a humble product idea.

Learn more.