Did you know that YOU can edit Microsoft’s online help documentation? With Microsoft’s acquisition of GitHub, it now stores (most of) its documentation in GitHub repositories, and is managing any changes to that documentation through GitHub. (The transition process is still not complete but they’re working on it.)
I’ll freely admit, I was a little nervous about little old me making changes to the documentation at first. But then my friend Tom Resing at Microsoft sat me down and explained the process and I realized it’s not as scary as one would think. (The key is that any change you make will be submitted for approval. Don’t worry; you won’t accidentally delete the whole document!)
First, ensure you have a GitHub account.
Providing Feedback
If you just want to provide your two cents about how the page could be improved, you can leave a comment, which essentially is opening an “issue” in GitHub. Content editors at Microsoft are able to review issues and can choose how to address the issue presented. (GitHub provides a nice interface for resolving issues and closing them, so you can eventually see if someone resolves your issue.)
To leave a comment on the page, navigate to the bottom of the page. You have several choices. You can either provide feedback on the product as a whole (such as SharePoint Online) or you can leave feedback on the page.
Note that if you click the button that you want to provide feedback on the page, you will get a screen that will ask you if you authorize a connection between GitHub and Microsoft.com.
Once you authorize access, if you click the button again, you will now see a form embedded in the Microsoft page. You can use the form to submit your feedback.
Note that if you are comfortable with GitHub, you have the option of submitting your feedback right on the GitHub site. Click on the “directly on GitHub” link in the drop down menu will take you right to a page in GitHub where you can add your comments.
Submitting Changes
If you want to do more than suggest changes, but you feel up to the challenge of actually submitting a change, you can do so.
Notice the Edit button at the top right of the page you want to edit. Click the button.
This will open the page in GitHub.
Go ahead and click on the pencil icon at the top right. A message at the top lets you know that it will create a branch in your own fork since you don’t have edit access in the live repository.
You will see a message at the top of the page that says “You’re editing a file in a project you don’t have write access to. Submitting a change to this file will write it to a new branch in your fork <fork name>, so you can send a pull request.”
You’ll notice that, since this is GitHub, documentation is written using Markdown. (Note that I find it helpful to copy the page into Word, edit my content in Word, then use the Word-to-Markdown converter to turn it back into markdown. It’s much easier to me than trying to edit markdown right in the editor, unless I’m just submitting some minor change.)
After you have made your changes, navigate to the bottom of the page and submit a summary of your changes and click on the “Propose file change” button.
This will take you to a page where you can see the changes that have been made. At this point, you can click the “Create pull request” button. A pull request simply alerts the owners of the repository (at Microsoft) that a change has been made for them to review. It’s up to them to decide how to merge your changes into the live branch.
This will present you with a larger box where you can enter your pull request details.
You don’t really need to change anything here other than ensuring that the “Allow edits from maintainers” is checked so Microsoft folks can edit your edits as necesary. Once again, click the “Create pull request” button.
You will now be moved to the “Conversation” tab. If you have not yet signed the contributor agreement, you will see a message letting you know your submission isn’t complete.
At this point you will get an e-mail asking you to accept the Microsoft Contributions License Agreement.
You will now see your conversation thread has been updated to indicate at the “all systems are go”.
And if you go to the Files Changed tab, you will see a message that says that you have an open pull request and a message that says something like “<your fork> wants to merge 1 commit into MicrosftDocs:live from <your fork: your branch>”.
When your change is approved the Microsoft folks will merge your changes into the live fork and you will see a message that tells you your pull request was successful and your changes were merged.
And after that, you get your 15 minutes of fame!
That’s it! It might seem like a lot at first, but remember that once you’ve initially set up your GitHub account, and also accepted the CLA, you can skip those steps with subsequent edits. The main thing to remember is:
- Either submit an issue/feedback right within the documentation page itself, or
- Go to GitHub logged in as your GitHub account, edit the file, click Create Pull Request (both times).
That’s pretty much it!
Let me know if you were able to pull this off by leaving me a comment.