Tag: documentation

Keeping MS Docs Up to Date

One of the things that I like about the SQL Server docs (MS Learn Docs) is that I can fix things I find wrong. For years we had downloaded Books Online from installs, then we have BOL on a site, but those were mostly updated when a new release came.

Now we have MS Learn, and a regularly changing set of docs. If you haven’t taken advantage of these docs for SQL Server, you should. Bookmark: https://learn.microsoft.com/en-us/sql/sql-server/?view=sql-server-ver17&redirectedfrom=MSDN

I help change those. It’s part of my contribution as a Microsoft MVP, but it’s also something that I enjoy because it makes my life easier. This post will look at how I do this.

Note: You need a GitHub account.

A Recent Change

Someone posted a note about multi-column primary keys, noting that the docs said we could use up to 16 columns, but they were able to do 17. I went to this page, Primary and Foreign Key Constraints , where in the first bullet list, there was a 16. This was the week of 24 Nov.

Now, a week later as I write this, it says 32.

When I saw the 16, I decided to test things. I set up scenarios, I checked against multiple versions, and I verified that 32 was the right number.

Then I clicked this edit button on the page:

When I did that, I was sent to the GitHub repo for the docs, which is in the MicrosoftDocs org. You can see what I see below. A lot of this is their markdown template, and can be ignored.

On the right is a pencil edit button. I clicked that.Note this says I’ll get a fork of this repo. That’s what I want.

When I click the pencil that, I go to the same page, but without any rendering. Note I’m still in the MS repo, but the blue note at the top says my changes will be written to my repo in a new branch.

When I knew I had seen an error, I scrolled down in the page and found the list. Here we see my 32 highlighted. This said 16 a few weeks ago.

I can edit this, so I’ll change this to 64. Don’t worry, I can’t affect the live docs. When I do this, I’ll then click “commit changes” in the upper right.

After clicking this, I get a commit dialog. Copilot tries to guess what I’ve done and it’s a good start. I typically edit the description a bit.

Once this is done, and I click Propose changes, I get a pull request page. In this case, notice in the top image, I see this is going from my repo, from a specific branch, to the MS repo for comparison. I’m asking them to pull my changes.

Below this, I see the file(s) changed. In this case, one change.

I typically just click “Create pull request” for my changes and then the MS automation takes over. A form appears that shows the PR created and the status (if it can be merged). Since these are quick, usually there’s not problem with a clean merge.

I get an email from the automation thanking me for the contriution, letting me know an author has been notified.

If there are comments, I’ll get emails on those. When this happens, sometimes they let me know there is something else needed or I should amend my PR. Sometimes they tell me they’re closing the PR and incorporating the change into something else. I’ve had my change get someone thinking and they might take my idea and add something else in their own internal PR.

If someone approves my PR, they’ll add a tag from their side, and the change is merged and a rebuild happens. Here’s the email I get.

Then my change is live pretty quickly.

I probably submit 5-10 a year, almost one a month. I don’t find a lot of issues, though I do sometimes take the time to add a new example that might serve me, or others. I should do more of those.

If you want to submit your own corrections, feel free. If you don’t, and want me to do it, send me a note and I’ll submit the PR.

December 10, 2025
How Wrong is Stack Overflow?

I chose the title slightly to poke at Stack Overflow (SO), but the same take expressed in this tweet could be said about SQL Server Central. It’s not quite the same as anyone can answer questions on SQL Server Central.

The tweet is a (long) hot take from Jerry Nixon, a C# developer and MS evangelist in Denver. Essentially he says that a lot of the SO answers are wrong, especially as the software and languages change. Old answers are upvoted, and remain at the top of the list, even as newer answers might be better. People don’t like the behavior on SO of moderators and people who post, which is something we’ve tried to avoid or limit here at SQL Server Central. We want there to be professional discussions. SO also doesn’t allow much discussion or nuance in the questions or answers.

This isn’t just a SO problem or am SSC one. It’s a problem when we have lots of documentation, blogs, etc. on the Internet that search engines find and surface when it’s popular. Across time, these popular outdated posts remain, just like older documentation that doesn’t apply to a current version and this can be frustrating. I am even starting to get annoyed by the MS Learn docs for SQL Server as some functionality change across versions. It isn’t easy to determine what applies to which version, especially when subtle changes are made in how things work. If something is new, usually that’s clear, but when things change, it isn’t. The examples aren’t well maintained, or there are too many of them to really understand how and why a change in versions can affect your code.

I do wonder if we ought to somehow limit content that we see by default to more recent content. Or maybe Google/Bing/et al ought to let us set that as a preference. In general, I want more recent content, but at the same time, I don’t want to say “give me blogs about something from the last month only.” It’s possible I use something that’s rare and the most recent blog is 7 months old.

More, I wish we had better ways to tag content online as relevant for certain things or not. I can’t think about the entire world and all the different types of content, but I can think about technology and software. I’d like to know if someone write a highly popular and useful post on PowerShell 5 that was written and tested on that version. I can understand that it’s not necessarily tested on PoSh 7, though it could work. It could even be the best solution. The same thing applies to Python 3.8 or T-SQL for SQL 2016 or any other software.

The challenge of keeping things up to date is a big one, especially as more companies move to release software more often. I’m always pointing out issues in the RG docs. Since we release every week or two, each product team has a busy job in ensuring documents are up to date, which is easy for the reference pages. This is a bit harder when there are articles were we explain how to use a feature or we have a walkthrough of the software. I don’t know if AI will help here, but I do think this is a place where AI might be able to help vendors at least keep up with changes. When code changes, update docs, all the docs including examples.

I do also think dating content is important. Microsoft tried to stop doing this with some things and many people complained. Content needs a date. It might still be valid or useful, but without a date, we have no idea of the context in which it was produced. That might help us decide if it’s still relevant, useful, or if we need to continue searching further.

Steve Jones

Listen to the podcast at Libsyn, Stitcher, Spotify, or iTunes.

August 9, 2023