When Microsoft gives bad advice, who pays?

Writing great technical documentation is a difficult job. That’s why it usually takes a small army of copy editors and technical editors and development editors and proofreaders to turn a manuscript into a book. The same quest for clarity is why articles in the Microsoft Knowledge Base are so highly formatted and why the lists of instructions sometimes go on at great length.

When writing detailed technical instructions, the most common mistake an inexperienced writer makes is to assume that the reader appropriately understands all related technical issues. The second most common mistake is to gloss over a key step in a complex procedure without sufficient explanation.

Amateur writers make these mistakes all the time when they dive into complex technical topics without the help of a team of editors or experienced technical writers. But what happens when the author is a Microsoft employee, and his work appears on a blog that represents the official word from a major development team? The results can be unfortunate, even disastrous, as this March 27 post from Microsoft’s IE blog illustrates all too clearly. The author identifies himself as a tester working on IE7 setup:

I have read that a number of you have seen the following error when attempting to install the IE7 preview:

“Error loading C:\WINDOWS\system32\msfeeds.dll The specific procedure could not be found.”

This error is permissions on registry key X (usually hkcr\.tif) being set to read only on the system. I want to talk about a couple of things to give some help in working around this bug and to explain what is happening.

It’s an interesting and generally useful technical discussion of why this bug occurs. But the post goes horribly off the rails when the author includes step-by-step instructions designed to work around the bug. Here’s the beginning of the discussion and the full numbered list of instructions:

The first step is open your updspapi.log, which can be found in the "windows" directory, and search for "Access is denied" in it.

In the area of the "Access is denied" errors, there will be an entry that reads: "Setting registry value" and then a key name. This is the locked key that is causing the problem. To change this you need to do the following:

1. Go to Start then "Run" type "regedit" in the run box and enter.
2. In regedit expand the appropriate registry (usually HKEY_CLASSES_ROOT or HKEY_CURRENT_USER) in the left pane and locate your key.
3. Right click on the entry in the left pane, select "permissions..."
4. In the permissions box select the "administrators" group.
5. Click on the "Advanced" button at the lower right.
6. Select administrators and click edit.
7. In the next dialogue check to allow box for "full control".
8. Save and close the registry.
9. Install IE7

Let’s add up the things that are wrong here:

• That part at the beginning that says , “The first step is…”? That should be item 1 in the numbered list. If you’re going to number your instructions, the list should include all the steps.
• In the paragraph right above the numbered list, there’s a reference to a “key name.” This assumes that the reader is familiar with the structure of the registry and knows what a key is. Bad assumption.
• Numbered step 2 says to “expand the appropriate registry” and then gives me the names of two hives and tells me to locate the key. Once again, this instruction assumes that I know my way around the registry editor and can expand and select and edit items without further instruction. Another bad assumption.
• Is the key I’m looking for in HKEY_CLASSES_ROOT or HKEY_CURRENT_USER? Why is this article forcing me to guess? What happens if I guess wrong?
• Steps 3 through 8 explain how to reset permissions for a registry key. If I do this wrong, I can undermine my computer’s security or cause serious problems for the operating system or an application. So where’s the boilerplate text that warns the reader that editing the registry is dangerous?

If this post had been published as a Knowledge Base article, it would look very different. For starters, it would include this warning:

If you use Registry Editor incorrectly, you can cause serious problems that may require you to reinstall your operating system. Microsoft does not guarantee that problems that you cause by using Registry Editor incorrectly can be resolved. Use Registry Editor at your own risk.

And the steps would be so precise that you would not have to guess what to do next.

Now, I really don’t mean to pick on the author of this post, who clearly meant well and has passed along some useful information to a technical audience. But these are absolutely terrible instructions. You might argue that only an audience of uber-geeks and webheads is likely to read the IE blog. To which I say, “Uh, no.”

If you type ie7 setup failure into Google or MSN Search, this blog post turns up near the top of the search results list. That’s exactly what a not-very-technical friend of mine did on Monday after he tried to install IE7 Beta 2 and experienced a setup error. By the time my friend called me, from 500 miles away, he had been hacking away at his registry with the digital equivalent of a blunt machete for two hours. He had merrily adjusted permissions on several  keys (including those for the top-level HKCR and HKCU hives) without realizing that he was creating a potential disaster for himself. As soon as he rebooted, he encountered mysterious errors and discovered that none of his third-party software programs worked anymore, and he couldn’t even use System Restore to roll back the changes. I advised him to back up his data files, track down the restore disks for his notebook, and start over. There’s no way I could help him troubleshoot this problem long distance, especially when he isn’t entirely sure what he did to cause the problem in the first place.

The lessons learned?

• Thanks to search engines, random stuff on the Internet has the potential to reach unexpected audiences.
• Thanks to those same search engines, incorrect and obsolete advice hangs around forever.
  
• If you write vague instructions, Murphy’s Law practically guarantees that someone will follow them incorrectly.
• Before you advise anyone to do something that might be dangerous (like poke around in Registry Editor), be sure you warn them of the consequences.

Microsoft has earned lots of praise for the freedom it extends to employee bloggers, and the last thing I want to do is argue that they should dial back on that freedom. But a little peer review couldn’t hurt, especially for any post that offers detailed instructions that would normally appear in a Knowledge Base article.

Oh, and Microsoft? You really, really ought to have someone take a second look at that post, especially now that IE7 Beta 2 has been turned loose on the public at large. Something tells me my friend isn’t the only one who’s going to screw up a perfectly good Windows installation by trying to follow those fuzzy instructions.