Shortcut: Fixing or improving SQL Server Books Online

I mentioned in an earlier post that I think the online version of Books Online (BOL) is now superior to the version that you can install locally.

I particularly like the way that the online books are now cross-version ie: each page covers all supported versions, instead of having a separate page for each version.

But one of the really big bonuses is that you now have the opportunity to change the documentation if you think it’s incorrect or you think it could be improved. Microsoft have placed all the documentation in a Git repository and you can change it. Doing so is easier than you might expect.

Let’s look at an example.

I’ve searched for the LEN function in T-SQL and found the page:

Note the small list of faces appearing under the command name. These are people who have contributed to this page.

Now while I’m reading the page, I see this:

I’m puzzled why that example is specific to AdventureWorks2012. That code would work on all AdventureWorks versions. So let’s try to change it. At the top of the page, there’s an Edit link.

I’ll click this and I’m taken to the page in Git:

Note in the top right-hand corner that I’ve already logged onto Git. Also notice the Edit pencil. Now I can’t just directly change this info, so what I do is click this to “fork” the project so that I have my own copy to edit.

Now I can make the change that I want to:

And at the bottom of the page, I explain why:

Then I click Propose file change, and I’m taken to a page that asks me to create a pull request.

Git runs some automated checks, and makes sure that I’m not suggesting a change that can’t easily be merged.

If I’m happy with the differences shown, I just click Create pull request and again another time. This page is then sent off to the person who is responsible for maintaining the page:

If they agree, your change will be merged in. Either way, you’ll receive emails telling you what’s going on.

If you have added a lot of changes or code, you’ll also receive another email asking you to agree to be a contributor.

This is a great new option and once you’re used to it, very easy to do.

2018-07-05