Troubleshooting tips are not formal product documentation

Date:April 24, 2006 / year-entry #143
Orig Link:
Comments:    20
Summary:The Microsoft Knowledge Base is filled with product support tips, but be careful to understand the scope of those tips. Generally speaking, information provided in the Knowledge Base exists for troubleshooting purposes, not for program design. That's why each article lists specifically which operating system it applies to: There is no guarantee that a particular...

The Microsoft Knowledge Base is filled with product support tips, but be careful to understand the scope of those tips. Generally speaking, information provided in the Knowledge Base exists for troubleshooting purposes, not for program design. That's why each article lists specifically which operating system it applies to: There is no guarantee that a particular tip will work on future operating systems. This is particularly true if the tip recommends digging into a program's internal data structures, persistence formats, or files. The Knowledge Base article is for helping you get yourself out of a mess; it is not formal product documentation. Think of it as a Microsoft version of Experts Exchange. (I always wondered how many people misread that site as "Expert Sex Change".)

Knowledge Base articles typically come from the product support groups. Someone might solve a problem with a customer's machine and say, "You know, I bet other people will run into this problem, too. Let me document how I fixed it to save time for the next person." They'll write up a Knowledge Base article and add it to the database. Sometimes (rarely, in my experience), they will run the article past the product group responsible for the topic area for a technical review before publishing it. In other words, articles in the Knowledge Base come with a lower "level of service" than formal product documentation; they were not necessarily approved by the product group. If it helps you solve your problem, then great! But there's no promise that it will, and neither is there a promise that the solution will work in the next version of the operating system. It's just a bunch of IT folks sharing war stories.

The explanation above is also wrong.

Due to the quick publishing times of the Knowledge Base compared to the formal product documentation, a product group will often take a shortcut and publish their documentation via the Knowledge Base in order to get the information out quicker. As a result, some Knowledge Base articles really are formal product documentation disguised as troubleshooting tips.

Sometimes a Knowledge Base article does go through product group review, such as the pair of articles describing how to use rundll32 to debug a control panel and how to start a control panel programmatically. The programmatic method is to use the Control.exe program, which has been the supported mechanism since Windows 3.0. The rundll32 technique is only for debugging purposes. If you use the rundll32 technique in your production software, you will run into problems because you're bypassing the official entry point and going for the internal entry point. The official entry point has the compatibility hacks, knowing about the names of control panels that have been retired and redirecting them to their replacements, knowing where shell special folders have moved to, and knowing how to compensate for 64-bit programs trying to run 32-bit control panels and vice versa. But if you go straight to rundll32, you miss out on all this. That's why the article says that the rundll32 method is for debugging purposes, not for production use.

The bad news for you, poor reader, is that it's not clear from the text of the article which type of article you have. Is it (1) an as-is tip from a product support technician in the hopes you might find it useful, (2) an as-is tip that the product group approved as solution that they will support in the future, or (3) product documentation disguised as a support tip?

Personally, I can tell the difference between {1,2} and {3} just by the tone of the article and the general sense of "Gosh, I wonder if the product team really expects to be supporting this mechanism in the future." Maybe I was just born with this skill (or perhaps developed it early on in my career as a software developer), because it seems most people can't tell the difference.

Here's the question to ask: Does the proposed solution rely on what appears to be a side-effect, internal behavior, or internal data structure that a programmer would want to reserve the right to change in the future? Does it feel like a cobbled-together solution? Does it involve duct tape and string?

I'm sorry it's such a mess, but with hundreds of thousands of Knowledge Base articles in existence, it would be impossible for me to go through and tag each one. You'll have to use your best judgement.

Comments (20)
  1. Stephen Jones says:

    Actually, my problem with the knowledge base is that they are too slow off the mark to publish tips. Often I’ve come across a problem and ended up finding the solution myself with nothing published in the knowledge base. This particularly seems to happen if the symptoms, though not the cause, are in a third-party app.

    I must take the opportunity to say however, that the MSKB, whatever its faults, is a formidable piece of work. There is nothing that comes close to it in thoroughness and ease of use.

  2. Andy C says:

    {3} is usually easy to spot, because it generally doesn’t actually seem to describe a problem at all. These are the ones that are really quite annoying when you are (shock, horror) actually trying to find a solution to something as they just clog up the search results.

    {1,2} are much harder. Generally I tend to assume {1} but I’m not at all surprised by the number of people that don’t.

  3. darryl says:

    not to mention the ones that don’t make it to the public knowledge base.  I find nothing more frustrating then spending hours diagnosing a problem, then phoning up a PSS and finding a solution is in an unpublished article.  

  4. Adam says:

    When experts exchange first started they didn’t use the dash in their domain name.  I guess people complained about it being blocked by filters.

  5. Alun Jones says:

    Experts Exchange has the feel of one of those sites that re-packages Usenet as if it’s part of its own forum – that always makes me irritated.

    Don’t forget that KB articles can also be "Community Solutions" – posted by MVPs, when the product team hasn’t documented something (either in, or out of, the KB) very well.

  6. Is it Init Common Controls Ex or Init Common Control Sex?

    Also, what about Pen Island?

  7. Chatbot 3000 says:

    Don’t forget such classics as Who Represents? ( and Powergen Italia (

  8. Funny you should post this… I just ran into a knowledge base article that is disavowed by the product group.

    KB article re: IIS:

    IIS disavowal:

    "You should know by now that just because it is a KB does not mean it is a bug in a Microsoft product…"

  9. peterchen says:

    IIRC Experts Exchange for a brief time owned the domain. After some fun poking and unwanted traffic, they quickly dropped it again.

    KB sometimes has weird or even questionable anwers – still it is a valuable resource I’d miss. I guess every piece of programming material requires good judgement of the developer.

  10. Norman Diamond says:

    First, thank you for understanding one of the frustrations that a lot of your customers have, thank you for hinting that you find it almost as frustrating as we do, and thank you for explaining pretty well how it happened while not trying to justify it.

    > Maybe I was just born with this skill (or

    > perhaps developed it early on in my career

    > as a software developer), because it seems

    > most people can’t tell the difference.

    I think it’s one of your psychic powers.  I’ve found the Knowledge Base pretty much random, some good advice (which really does help), some bad advice (which sometimes wastes time but sometimes can be harmful), some on general programming and some on specific bugs in specific products, etc.  I never thought of trying to categorize them the way you do.

  11. 8 says:

    Using ShellExecute on a CPL file is bad?

  12. Jamie Anderson says:

    I’ve just had a look in my registry to see what happens when you use the default ShellExecute action on a CPL file, and look at what I found in "HCKRcplfileshellcplopencommand":

    rundll32.exe shell32.dll,Control_RunDLL "%1",%*

    This is on a standard XP SP2 installation on an x86 box. As far as I’m aware, I haven’t done anything that would cause this to change from its default value.

    If using RunDll32 is wrong, then why is my copy of Windows doing so, presumably by default?

  13. Nathan says:

    "then why is my copy of Windows doing so, presumably by default? "

    I’m not a Windows user – but the answer is obvious: if the internal behaviour changes in say Vista, Microsoft can update the ShellExecute for .cpl in Vista to do whatever’s right.

    Unless you can see into the future, you can’t and your software is broken for Vista users.

  14. piers7 says:

    It’s high time Microsoft actually addressed this problem at-source. Life would be much easier if the barrier to editing (or augmenting) the formal documentation was easier for Microsoft employees (and/or the public at large), so people didn’t have to use the KB as one big postscript. Inevitably the formal doco will be wrong/incomplete – why not come up with a better process to manage it.

    Some tagging system where KB articles could be automagically liked from the original documentation would be good too. It’s a bit tough to expect someone to read the doco and then scan through all the issues, so typically the problem-resolution is only discovered after a significant amount of wasted time.

    If we can have blog feeds on the MSDN home page, can’t we have (moderated) wiki content / comment space within the library?

  15. Mike Dimmick says:

    I’d like to add that *blogs* are not formal documentation. It’s just too hard to subscribe to and keep up with every MSDN employee or even team blog that relates to a given subject, filter them all, and ensure that you’re not misled by half-given information.

    I feel that recently MSDN Library has been slacking, badly. We’re nearly at Beta 2 of Windows Vista and there’s nearly no documentation. It’s not acceptable.

    A primary responsibility of any platform developer is to ensure that the platform can be used – there’s no point building the platform otherwise – and without good, detailed documentation – overview, story and functional detail – it cannot be used.

  16. Juan says:

    Adam/Peterchen:  close, but Experts Exchange never registered the domain (iirc.)  They were about to when the guy who was going to do it for them pointed out what else it spelled.  That’s when the dash appeared.  (/me never did any real work for them, I just hung out and ate the free subway sandwiches at the company meetings when it was a two-guy operation.)

  17. Matt Sullivan says:

    I love my language reference documentation. It attempts to tell me exactly what I want to know. I could possibly take it and make a fairly equivalent compiler(given lots of time).

    I hate my sys admin documentation. It reads like a 5th grade science book and does not help me get much of anything done. Taking these docs and trying to make a product would be an exercise in futility. A better job done here would negate much of what I use the KB for.

    As for the KB updating, I’ve been trying for 2 weeks now to get article 917385 changed. The person who wrote it agrees there is a problem with it and has submitted the change 2 weeks ago. It still hasn’t been updated.

  18. Neil says:

    I guess KB 293215 falls into category {1} as it’s not totally accurate (SW_SHOWMINIMIZED leaves the window active which SW_MINIMIZE does not).

  19. If Microsoft publishes information on how to perform some task or fix some problem, is the task or fix now documented? And supported?<br /> <br />Raymond Chen occasionally dips into this question and recently posted thoughts on the officialness

  20. I have talked about the Microsoft Knowledge Base article that describes how to run Regional and Language…

Comments are closed.

*DISCLAIMER: I DO NOT OWN THIS CONTENT. If you are the owner and would like it removed, please contact me. The content herein is an archived reproduction of entries from Raymond Chen's "Old New Thing" Blog (most recent link is here). It may have slight formatting modifications for consistency and to improve readability.

WHY DID I DUPLICATE THIS CONTENT HERE? Let me first say this site has never had anything to sell and has never shown ads of any kind. I have nothing monetarily to gain by duplicating content here. Because I had made my own local copy of this content throughout the years, for ease of using tools like grep, I decided to put it online after I discovered some of the original content previously and publicly available, had disappeared approximately early to mid 2019. At the same time, I present the content in an easily accessible theme-agnostic way.

The information provided by Raymond's blog is, for all practical purposes, more authoritative on Windows Development than Microsoft's own MSDN documentation and should be considered supplemental reading to that documentation. The wealth of missing details provided by this blog that Microsoft could not or did not document about Windows over the years is vital enough, many would agree an online "backup" of these details is a necessary endeavor. Specifics include:

<-- Back to Old New Thing Archive Index