Changes to Knowledge Base articles used for Cumulative Updates

This post has been republished via RSS; it originally appeared at: SQL Server Support articles.

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 Picture1.png

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

    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:smiling_face_with_smiling_eyes:?. 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

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.

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

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.