Tag: Microsoft

One of the neat things at Microsoft did last year was put Books Online in GitHub. This is in the MicrosoftDocs org under the sql-docs repo. The organization is a bit funny, but once you get used to it, you can find the docs.

One of the neat things that is available now is that anyone can edit Books Online. You can’t edit the live versions in GitHub, nor the versions published on Microsoft’s site (or downloaded), but you can submit your changes as a pull request, which Microsoft will review the changes, and if they like them, the changes can get added to the official docs.

This post shows how you can do this.

Requirements

First, you need a Github account. This is free, and you will end up with a fork (copy) of the official repo in your account when you edit.

Second, you need to learn a little markdown. Not much, but enough to make formatted changes. I like this cheatsheet, but there are plenty out there (kidding).

Editing BOL

When you go to a page in the online BOL, you should notice a short menu in the upper right. It has Feedback and Share links, but also an “Edit” link. You can see this in the image below.

If you click Edit, you’ll be taken to the page in Github. Below, I have the Backup page shown. Note the path near the top (by Branch:live) of sql-docs/docs/t-sql/statements/backup-transact-sql.md. This is the file in the repo. You’ll need this.

This is the real repo from Microsoft, and you won’t be able to edit it. If you click edit (a pencil icon on the right side, just above the doc and to the right of the Raw|Blame|History buttons, you’ll get this:

That’s fine. You can edit the page and then save this in your copy of the repo. In this case, I actually wanted to edit this page to add the NUL device. I scrolled down and found the area I wanted to edit. For ease of viewing, I’ve highlighted the place I edited the file.

Commit

All of you reading this should be familiar with version control. If you’re not, learn that.

To commit my change, I scroll to the bottom of the file and I’ll see the propose file change dialog. I can enter a title (meaningful for the change) and a comment that will let someone know what I’ve done.

Once I do this, a new branch is created in my repo. If I look at the result page, I’ll see this:

Reading this, I see that in my fork (way0utwest/sql-docs), I have a new branch (patch-4) that was created. Below this are the details of the commit, but essentially I have a copy of the official Microsoft repo in my area, with one new commit.

The Pull Request

A pull request (PR) is a notification to a repo that there are changes that someone wants to merge into that repo. In this case, a pull request will let MS know that my change is ready to merge, and they can review it.

To start a PR, click the green button in the image above. By default, I’ll get the same commit comments I had listed above. In this case, I see this:

Note, there are a couple important things here. First, this change is “able to merge”. We see that near the top. If you’ve made substantial changes that don’t necessarily merge cleanly, or you have an old copy of the repo, this won’t work. Go back and create a PR to update your repo from MS (you can approve this) and then make your changes.

Second, make sure that your comments make sense to the person that will review this. In my case, I wanted to have more complete docs with NUL as an option (since it is) and I noted this is a target. I could expound why here or add more details. I try to ensure each change I’ve made has a sentence, so if I added a note to a different place in the docs, I’d have a second sentence here.

Click “Create pull request” to complete this. Someone at MS will be notified, and you’ll get an email. In my case, I got this:

Waiting

The next step is to wait. I’ve submitted four or five minor PRs that helped complete or clarify docs. In some cases I got a note from the repo maintainer the same day, some took 3 or 4 days.

In any case, you may get a message that your change is accepted and it’s been merged. In this case, you’re done and I thank you for improving BOL.

You also may get a message back in your PR that there are other changes that need to be made, or on rare occasions, an conflict has occurred. In that case, you may need to edit your change, make a new commit, and a new PR.

This is a great model that Microsoft has given us to allow the community to issue corrections. Prior to this all feedback would get emailed to someone at MS, without any real organization. Or MVPs would send in feedback, but someone would need to interpret that and make a change. Now the community can easily make a change and help improve and correct our docs.