Microsoft Docs, is the website on which all of Microsoft’s official documentation sits. Did you know that the documentation is open sourced and that anyone can contribute to it? Because you can, Microsoft Docs is hosted on GitHub, meaning you can issue a pull request (PR) to any of the Microsoft documentation to correct or add anything.
Contributing to Microsoft Docs was the thing that made me learn how to use Visual Studio Code, Git, GitHub, and Markdown. I used to believe that all other things were for developers and I didn’t need to learn them or know anything about them. But, as I said that all changed when I discovered I wanted to contribute to Microsoft Docs.
I want to walk you through the process of contributing to Docs from start to finish using more than just the web interface.
Install Visual Studio Code
My editor of choice is Visual Studio Code (VS Code), there are other editors out there however some of this walk through will be very specific around using VS Code.
If you haven’t got VS Code installed on your system, please download and install it, it is a free tool.
Leveraging the VS Code Extension library helps to add features, themes, and additional services into VS Code. There are several extensions that help make the process of contributing to Microsoft Docs easier and they have been bundled together by the Docs team into the Docs Authoring Pack, so you can install them all at once.
So, our next step is to install this extension pack.
Click on the Extensions button down the left-hand side menu of VS Code. Search for “Docs Authoring Pack”.
Visual Studio Code ExtensionsIt should be the first one in the list, click on the small green Install button just beneath it. VS Code will start to install the various extensions that are bundled within this extension pack, it may take a few minutes.
Install Git
Git is an open source program that can help with source control, it is widely used by the IT community. If you head over to https://git-scm.com/ and download the relevant version for your computer, then install as per the instructions.
Once you have Git installed on your computer, there is one piece of setup information you should do now.
git config --global user.name "Sarah Lean"
git config --global user.email sarah@fabrikam.com
Replacing with your information. This information helps to identify who you are when you contribute to projects. I wrote a Getting Started with Git blog post for those interested in reading more about Git.
Create GitHub Account
If you already have a GitHub account you can skip this section, however if you don’t have one you will need to sign up for one. It is free to sign up for an account and you just need to create a username, provide your email address, and create a password for an account to be created.
Find documentation you want to correct or add to
Now that you the basics setup you need to find documentation that you want to contribute to or correct. Now that could be changing sections that have gotten out of date or even just correcting a spelling mistake.
Edit a Microsoft Docs page
I’ve found a doc that I want to update, it’s only a minor change but I want to contribute and correct it for future readers. At the top of the Docs page you will see an Edit button.
If you click on this Edit button it will take you to the GitHub repository which is the source, or master copy of the Doc. For minor changes you could utilise the GitHub GUI interface to make changes, but I want to walk you through the process for larger changes.
To make our change we need to make a copy of the documentation on our local computer, this first step in doing that is to Fork the repository. Which creates a copy in your GitHub working area.
Fork a GitHub repository
Once the fork has completed GitHub will load your copy of the repository. The next step is to take a copy of that repo onto your computer for editing, to do that we carry out an operation called Clone.
Find the green button that says Clone or Download on your screen.
Clone a GitHub repoIf you click on that button a URL will display, copy that.
Now open up VS Code, and click on Terminal > New Terminal.
You’ll see a console open at the bottom of your screen, in here we want to change to the directory you want to copy the documentation into. I usually use the Documents folder on my computer for GitHub files, so I type:
cd documents
and then issue the command
git clone **INSERT THE URL YOU COPIED EARLIER**
You will now have the documentation copied to your local computer. Within VS Code, click on File > Open Folder and browse to the folder you just created and the contents will be available for browsing and editing within VS Code.
Edit the Doc
Now you have the documentation on your computer you can start to edit it and make the changes that you want to contribute.
GitHub Document Location
I’ve forked and cloned a copy of the Windows Server Docs repository on my computer and I want to edit one of the files in there “Guidelines for troubleshooting DNS-related activation issues”, to find where that document is located within the new folder structure I can refer back to the GitHub page that we first went to:
The highlight section breaks down the file path for you, the file I want to edit is within the WindowsServerDocs folder and then in the Get-Started folder.
Visual Studio Code folder structure
The file is now open within VS Code and I can start to edit it. The file is written in a language called Markdown. There are certain syntaxes that you need to understand to format text within Markdown, such as using one star before and after text will make it *italic*. However, one of the extensions we installed earlier or the contributors guide can help you with that.
If you highlight the text that you want to make italic, then press ALT+M a new menu will open and you will have access to document formatting, select Italic and the extension will insert the relevant syntax for you.
In my case I am just make a simple correction to the text, so I find the section in the document that I want to amend and make the change and save the document.
Push the change to your repository
The next step is to take your changes and push them to your repository on GitHub so you can then push them into the Microsoft repository.
To push the changes to your online GitHub repository there are two ways you can do this, via the GUI within VS Code or through the terminal command line interface. I used to do everything through the terminal but have changed over to using the GUI and managing everything that way so I am going to use that version today.
After you’ve saved your changed you should start to see a blue icon next to the Source Control icon on your VS Code bar.
Visual Studio Code Source Control Icon
This indicates that there is a change you need to commit to your original source/repository.
If you click on the Source Control button it will show you a list of files that have changed, we want to Stage the change, which lets Git know what want to add to our next Commit. To do that right click on the file you’ve edited and click on Stage.
We now want to write a description of the change we’ve made, so others can follow our work.
Commit Stage within Visual Studio CodeAnd then click on the commit or tick icon to Commit that change.
Now the change is ready to be Pushed up to our GitHub repository. To do that click on the ellipse button and select Push. At this stage a pop-up box asking you to authenticate to GitHub will pop up. We are using an account that doesn’t have 2FA set up, however if you do you should follow these login instructions.
After a few seconds you should be able to go to your GitHub repository via a browser and see that the changes you made on your computer and now online.
Push your changes to the Microsoft Docs Repo
The next stage of the process is to take the changes you’ve made and submit them to Microsoft to review and hopefully merge into the official documentation page.
To do that we need to make a Pull Request.
GitHub Pull Request
Open up a browser and go to your GitHub repository, the copy of the Microsoft documentation you committed your changes to.
Click on the Pull Requests button when that page loads click on New Pull Request.
GitHub is quite clever, it recognises you forked a repository, make some changes and now want to merge those changes with the original repository.
As this is exactly what we want to do we don’t have to make any changes, we can click on the Create Pull Request button.
We are now presented with a comment section, it is best practice to use write something about the change you’ve made so that the person reviewing the files has a good understanding of your work and reasoning.
Once you’ve added your comment click on Create Pull Request.
Comparing Changes GitHub
Your change is now there for someone at Microsoft to review and hopefully merge into the official documentation!
Next Steps
Keeping the local copy of the repo in sync with the original can be a challenge, one which I talk about in a previous blog post. I'd love to hear your thoughts on the process for contributing to Docs and hear of your success stories!