Changes to Knowledge Base articles used for Cumulative Updates

Summary: In March 2020 we introduced inline, short description of fixes in the master Cumulative Update KB articles. We call those descriptions “blurbs” and they replace many of the individual KB articles that existed for each product fix and contained brief descriptions. In other words, the same one-two sentence description that existed in a separate article before, now appears directly in the master CU KB article. For fixes that require longer explanation, provide additional information, workarounds, and troubleshooting steps, a full KB article is still created.

Now, let’s look at the details behind this. SQL Server used the Incremental Servicing Model for a long time to deliver updates to the product. This model used consistent and predictable delivery of Cumulative Updates and Service Packs. A couple of years ago, we announced the Modern Servicing Model to accelerate the frequency and quality of delivering the updates. This model relies heavily on Cumulative Updates as the primary mechanism to release product fixes and updates. The new model provides the ability to introduce new capabilities and features in Cumulative Updates. As you are aware, every Cumulative Update comes with a Knowledge Base article. You can take a look at some of these articles in the update table available in our latest updates section of the docs.

Each one of these Cumulative Update articles have a well-defined and consistent format. It starts off with metadata information about the update, mechanisms to acquire and install the update, listing of all the fixes and changes in the update. In some rare occasions, there might be a section that provides a heads up to users about any known problems encountered after applying the update. In this post, we will focus on the changes introduced to the listing of the fixes and changes in the update. Usually what you will find is a table that contains a list of fixes with bug numbers, link to an article that describes the fix, area of the product to which this fix applies. Imagine a Cumulative Update with a payload of 50 fixes. What that means to a user reading the Cumulative Update article is 50 context switches in and out of that article (not including other links you might end up clicking and reading). We all agree that frequent context switching is not efficient – be it computer processing code or human brain reading things. So how do you optimize this experience and still maintain the details provided in the individual articles you click and read? Here comes the concept of “article inlining” to the rescue! Yes, we borrowed the same concept we use in SQL Server (e.g. scalar UDF inlining) and computer programming in general (e.g. inline functions).

We will take this opportunity to explain the thought process that went into this change and what data points and decision points we use to drive this change.

Justification for Using a Blurb

• The normal format used for the individual fix articles include: Title, Symptoms, Status, Resolution, References. For example, let us look at SQL Server 2019 CU1 article. The first one in the fix list table is FIX: Transaction log isn't truncated on a single node Availability Group in SQL Server 

  Let us click on the link and open this article to understand more details about this fix. Here is what we see: 

  The only useful information you get from this lengthy article is the symptom section. Usually the title of the article provides a summary of the symptoms section. Now look at other sections. Of course, we know this is a problem in the software – otherwise why will we be fixing it😊?. Isn’t resolution here obvious – that you need to apply this cumulative update to fix this problem? If we now moved the 2 lines from the symptoms section in this individual fix article to the main cumulative update article, then you can avoid all these round trips and context switches.

  You can go down the list of fix articles in that KB and you will find many articles that fit this pattern. Our content management team did a study of several cumulative updates from the past and found that a majority of the individual fix articles (to the tune of 85%) follow this pattern and can be good candidates to “inlining” the symptom description in the main cumulative update article table.

Criteria for Creating a Full KB Article

• If you go down the list of fix articles in that list, you will find articles with different patterns of information:
  1. After applying the fix, you need to perform additional actions to activate the fix using a trace flag. Example: https://support.microsoft.com/en-us/help/4517771/fix-orphaned-clr-sessions-cause-blocking-in-sql-server
  2. Instead of applying the cumulative update, you can choose to use the workaround. Example: https://support.microsoft.com/en-us/help/4530303/fix-data-masking-of-user-defined-functions-may-result-in-crashes-in-sq
  3. You may need to take special steps to apply this cumulative update. Example: https://support.microsoft.com/en-us/help/4533251/fix-upgrading-fci-passive-node-from-sql-server-2019-rc1-to-rtm-fails-w

In such scenarios, we carefully evaluate if we can perform inlining and still manage to represent this additional information in the main cumulative update article. These are good candidates to have an individual fix article.

• You will also encounter articles which is very detailed. For example see the error log snippets and other details present in https://support.microsoft.com/en-us/help/4521659/fix-sql-writer-service-fails-to-back-up-in-non-component-backup-path-i .Without a doubt, these types of articles must stay as individual fix articles and do not qualify for article inlining.
• In SQL Server versions 2017 and 2019, product improvements or new capabilities (DMV’s, catalog views, TSQL changes) are shipped through cumulative updates. You will find plenty of examples about this in the CU article list we are using as reference. Don’t you agree that product related improvements should be documented in the product docs and not support knowledge base articles. Otherwise this will cause a disconnect when you look at product documentation.
• We have used this style of fix lists in the past with service packs. An example is https://support.microsoft.com/en-us/help/3058865/sql-server-2014-service-pack-1-release-information. Also, many modern products use release notes to convey all pertinent information about that specific update. For example: https://docs.microsoft.com/en-us/sql/azure-data-studio/release-notes-azure-data-studio?view=sql-server-ver15 and https://support.microsoft.com/en-us/help/4532891/update-rollup-1-for-system-center-service-manager-2019
• Another dimension to understand is the page views and hit rate from search engines for these individual articles compared to the main cumulative update article. Usually the page views for cumulative update articles is the order of thousands of views while the individual article are read very few times.

We started piloting this approach around March 2020 timeframe. The initial releases we attempted this style for were SQL Server 2016 SP2 CU12 and SQL 2019 CU3. Our friends and colleagues called it the “Attack of the blurbs!”. Some folks called it the "TL/DR version" of knowledge base articles. The reactions have been predominantly positive and encouraging. Of course, we will constantly fine tune these approaches with user feedback. As part of this change, we are also improving the content reviews done for the CU articles to ensure they contain relevant and actionable information for users.

One important callout we would like to make sure users understand is about the quality of these fixes. Irrespective of whether a fix has an individual article or an inline reference in the main cumulative update article, they go through the same rigorous quality checks established for cumulative updates in general. In fact, the article writing, and documentation process is the last step in the cumulative update release cycle. Only after a fix passes the quality gates and is included in the cumulative updates the documentation step happens. And we have already discussed how a fix gets described – an individual article vs inline blurb.

We hope this explains the changes you notice around the KB articles for Cumulative Updates.

From the support team: Joseph, Suresh, Ramu