Go to ...

RSS Feed

Microsoft Docs – Excellent, but Imperfect


Microsoft faced a huge task when they started moving all documentation for their products and services from TechNet and MSDN to its new Microsoft Docs (https://docs.microsoft.com) sub-site. When launched in June 2016, Microsoft Docs only contained the .NET documentation, Since then, most of the other content has gradually moved over under that same umbrella.

I like this idea, and I like Microsoft Docs. For whatever Microsoft product or service you seek help or instructions, you can find it in MS Docs. Today it is a site that every user of Windows, Azure, Office or any other MS service or product should bookmark. Especially for IT pros working in Windows-based environments, MS Docs can be a real time saver. It offers valuable help with setting up networks, deploying and troubleshooting Windows, and so forth and so on.

However, I have one vexing problem with MS Docs. Sometimes its documentation is really outdated. For instance, there are still pages starting with “Applies to Windows Vista.” Thus, this material has not been updated in past 10 years or so. This applies to certain commands and features still very much alive in Windows 10, that have new switches and features. The thing is, for Windows 10 such commands and features have changed A LOT. Thus, those docs should be updated. I understand that is an enormous task, but it needs to be done — sooner, rather than later, if at all possible.

Take the Microsoft Deployment Workbench (MDT) as an example. MDT is still widely used. The most recent version available is dated September 2017. MDT is fully supported, and there are no retirement plans for it in the foreseen future. Its full documentation is just under 1,200 pages when downloaded as a PDF from MS Docs. To read it through and check every line to see if the information is still valid, makes me feel sorry for whichever MS employee who take on this job. Luckily, some poor geek has already started. In fact, the PDF and online documentation release notes are already updated for Windows 10 version 1809. However, that’s just the release notes. Alas, not much else has been updated within the remaining 1,100+ pages. Browsing this documentation online, you’ll notice it says:

In this document, Windows applies to the Windows 8.1, Windows 8, Windows 7, Windows Server® 2012 R2, Windows Server 2012, and Windows Server 2008 R2 operating systems unless otherwise noted.

So, the release notes and the “Applies to…” section are not in sync. Not a big deal. But, in some cases old information is also out of date or irrelevant. While there are many things in this documentation that remain valid for Windows 8.1, they are no longer valid for Windows 10. In my opinion, over three and a half years after the release of Windows 10, all official documentation should cover the current flagship OS (Windows 10). It is not enough that MS changes its release notes to cover Windows 10, when in fact some details and instructions in the documentation no longer apply to that OS. This is especially true when such details don’t apply to Windows 10, or in the worst case scenario can make Windows 10 fail and crash.

In addition, when it moved content from TechNet and MSDN, Microsoft forgot to update many embedded links. It’s frustrating to Bing or Google something where the first link given seems to be a perfect match, and then to click that link and get a 404 error or be redirected to the Microsoft Store.

I faced problems with official MS documentation this week when preparing the next part for the MDT Deployment series I started last week. My issues this week seem come from a lack of documentation of a feature. This may be a topic slightly different from outdated documentation, but it’s still an important issue for a serious and devoted Windows user like myself (or our readers).

I never write a tutorial or instructional post based solely on “I know this stuff.” Instead, my writing is hideously slow because of the tests I make for each step. Thus, while editing the default MDT generated answer file Unattend.xml, and the settings file CustomSettings.ini, then doing test deployments in Hyper-V virtual machines, to my great surprise I got the following error message on target machines, whatever modifications I made:

Booting the test machine again, I got another error, this time telling me that Sysprep failed to apply the Unattend.xml answer file:

The fault, according to the error message, was in the answer file, during the Specialize pass. I am quite an experienced MDT user, and know my way around deployment and image customization. I also now how to create custom answer files. I checked my Unattend.xml, where everything looked OK. Upon validating that answer file, it came back with “No errors“. My conclusion: absolutely nothing wrong in my Unattend.xml.

To make the ensuing long story short, after three days of trial and error, I found out that including locale settings both in CustomSettings.ini and Unattend.xml causes Sysprep to fail. I never faced this issue before, because I never earlier used locale settings in CustomSettings.ini before, either. This time, because I wanted to write instructions about how to completely automate an MDT Lite-Touch Installation, I added locale settings as a demonstration to show how these settings should be added when required to the INI-file. In my own deployments, I’ve always included these settings solely in the answer file. Lesson learned: If you have locales (InputLocale, UserLoale, OS language etc.) already set in the MDT generated answer file, do NOT include them in CustomSettings.ini!

In my case, I could not find any documentation about this. This would have provided me with an easy fix (removing a few lines from INI-file) and avoided three days of needless toil and frustration. Quite often the Microsoft Docs official documentation is somewhat obscure, leaving it to the user to determine correct usage. And, most important, it is occasionally quite outdated. Microsoft, please, I know it will require quite a lot of work, but it would really be helpful to regularly check that your documentation is up to date.

That’s all this time!

Kari

Author: Kari Finn

A former Windows Insider MVP, Kari started in computing in the mid 80’s writing code for VAX / VMS systems. Since then, he’s worked in a variety of IT positions. He specializes in Windows image capture, customization, repair and deployment as well as Hyper-V virtualization. Kari is a proud Team Member at number #1 Windows site TenForums.com.

Tags: , ,

Leave a Reply