Changes to KB articles used for Cumulative Updates
Published Aug 18 2020 12:47 PM 4,957 Views
Microsoft

Back in March 2020, the main Knowledge Base (KB) articles for Cumulative Updates (CUs) started including inline description for fixes. We call those descriptions “blurbs” and they replace many of the individual KB articles that existed for each product fix but contained only brief descriptions. In other words, the same short one or two sentence description that existed in a separate KB article before, now appears directly in the main CU KB article. For fixes that require longer explanation, provide additional information, workarounds, and troubleshooting steps, a full KB article is still created as usual.

 

 

Detail

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 (CUs) and Service Packs (SPs). 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 CUs as the primary mechanism to release product fixes and updates, but also provides the ability to introduce new capabilities and features in CUs.

Historically, every CU comes with a KB article, and 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 CU main KB articles has a well-defined and consistent format: metadata information about the update, mechanisms to acquire and install the update, and a list of all the fixes (with bug IDs) and changes in the update. In some rare occasions when an issue is found after the CU is released, there might be a section that provides a heads-up to users about a known problem encountered after applying the update, and its scope.

Now imagine a CU with a payload of 50 fixes. If you want to know more about each fix, you’d have to click through 50 child KB articles (one per fix) and we received strong feedback that wasn’t a friendly experience. 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 shorter individual articles you used to click and read?

With the concept of “article inlining”! Yes, we borrowed the same concept we use in the SQL Database Engine (e.g. scalar UDF inlining) and computer programming in general (e.g. inline functions).

 

Why this change?

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. Besides user feedback, and because we are data-driven after all, we also looked at page views and hit rate from search engines for these individual articles compared to the main CU KB article. We found that usually the page views for the main CU KB articles is measured in the thousands, while the individual fix KB articles are read very few times.

 

Using blurbs

The normal format used for the individual fix KB article include: Title, Symptoms, Status, Resolution, and References. However, not all fixes are implemented the same way. For example, let us look at SQL Server 2019 CU1 article. The first fix in the table is FIX: Transaction log isn't truncated on a single node Availability Group in SQL Server, and when you install it, the fix is simply applied and enabled.

 

KB_Inline.png

 

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

 

KB_Full.png

 

The only useful information you get from this lengthy article is the Symptoms section. Usually the title of the article provides a summary of the symptoms section. Now look at other sections:

  • Status: of course we know this is a problem in the software – otherwise why is a fix needed?
  • Resolution: this seems obvious enough – that you need to apply this cumulative update to fix this problem.

By moving the two lines from the Symptoms section in this individual fix KB article to the main CU KB article, then you can avoid extra clicks and context switches.

You can go down the list of fix articles in that KB and find many articles that fit this pattern. Our Content Management team did a study of several past CUs and found that the majority of individual fix KB articles (to the tune of 85%) follow this pattern and can be good candidates to “inlining” the symptom description in the main CU KB article table.

 

Criteria for creating a full KB Article

However, you can identify KB articles in that list with different patterns of information:

In such scenarios, we carefully evaluate if we can perform inlining and still manage to represent this additional information in the main CU KB article. If not, then these are good candidates to have an individual KB article. For example, FIX: SQL Writer Service fails to back up in non-component backup path in SQL Server 2016, 2017 and 2... is very detailed, and includes error log snippets and other details that can’t be inlined.  

 

To each their own

In SQL Server 2017 and 2019, product improvements or new capabilities (such as DMV, catalog views, or T-SQL changes) are shipped through CUs, as there are no more SPs. You will find plenty of examples about this in the CU article list we are using as reference. Being improvements or new capabilities, information belongs in the product documentation, not in support KB articles. Otherwise this will cause a disconnect when you look at product documentation. Going forward, this is the pattern you’ll see.

We have used this style of fix lists in the past with service packs. An example is 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: Release notes for Azure Data Studio and Update Rollup 1 for System Center Service Manager 2019.

 

Going forward

As we mentioned, we started piloting this approach around the March 2020 timeframe. The initial releases we attempted this style for were SQL Server 2016 SP2 CU12 and SQL Server 2019 CU3. Our friends and colleagues called it the “Attack of the blurbs!”. Some folks called it the TL/DR version of KB articles. And while the reactions have been predominantly positive and encouraging, we will constantly fine tune these approaches based on 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. When we stated in the Incremental Servicing Model (ISM) post that “(…) we now recommend ongoing, proactive installation of CU’s as they become available. You should plan to install a CU with the same level of confidence you plan to install SP's (Service Packs) as they are released. This is because CU’s are certified and tested to the level of SP’s (…)”, we meant it, and are continuously making the process more robust. Irrespective of whether a fix has an individual KB article or an inline reference in the main CU KB  article, they go through the same rigorous quality checks. In fact, KB article writing and creating documentation is the last step in the CU release cycle: only after a fix passes the quality gates and is included in the CUs, does the documentation step happen.

Version history
Last update:
‎Aug 18 2020 03:24 PM
Updated by: