When Microsoft gives bad advice, who pays?

When Microsoft gives bad advice, who pays?

Summary: What happens when a Microsoft blogger tries to explain a complex technical topic without the help of a team of editors or experienced technical writers? What happens when the author is a Microsoft employee, and the blog represents the official word from a major development team? The results can be unfortunate, as one unsophisticated user found out when he ran into an IE7 setup bug.

SHARE:
TOPICS: Browser
33

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.

I don't mean to pick on the author, but these are absolutely terrible instructions.

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.

Topic: Browser

Kick off your day with ZDNet's daily email newsletter. It's the freshest tech news and opinion, served hot. Get it.

Talkback

33 comments
Log in or register to join the discussion
  • It's a BLOG, not a terchnical article.

    Look, a blog is a blog and anyone can put one up. (Why most want to I'll never understand.) If you visit a blog you do so at the risk of believing what it says. YOu name the subject and I'll find you a blogger or dozen's of them. Does they fact they can type make them the world's authority? No. Does it mean they are great writers? No.

    Read blog and drink a glass of water, at lest when your done you can p*ss them both away. shrug...
    No_Ax_to_Grind
    • This blog is different

      Hey, No_Ax, this isn't just Joe Random Blogger. It's the official public face of the IE team. It's hosted at Microsoft.com. Everyone who posts there is a Microsoft employee. They make official announcements there.

      Someone who runs across this page has every right to assume that it's going to be accurate. In fact, because of Microsoft's search engine ranking, these pages are going to leapfrog way above those written by random bloggers.
      Ed Bott
      • The audience

        One would assume that the audience for this blog would be
        highly technical people. They would understand things that the
        general populace would not. If the blog allows comments,
        somebody would post a correction.
        j.m.galvin
        • It comes up high in Google results

          It doesn't matter who the intended audience for this post originally was. If I'm Joe User and I run into this problem and Google the error, this page comes up high in the results. (A point I made in the original post.)

          There are dozens of comments on this post, but alas, comments are now closed, so no correction is possible.

          Read the conclusion of this post. Thanks to search engines, a nontechnical audience can find this sort of content, even if it was originally intended for a more technical audience. That's a real problem and one that tech weiters in particular have to be aware of.
          Ed Bott
    • And with bad spelling like yours

      No one would be able to get "terchnical" advice from you without laughing.
      itanalyst
    • I have to agree with No Ax on this one..

      It's a blog, not an article.

      Technical people will understand it..
      ju1ce
      • Picking on Microsoft

        There is always someone who will pick on Microsoft, even if the reason is not justified.

        Why not let them be?
        hectorb@...
        • The problem here is...

          This self-rightous author (of this ZDNet Blog) is destroying a well-intentioned individual that was trying to help the masses (of technical beta folks)

          He goes as far as stating that "his work appears on a blog that represents the official word from a major development team"

          Too bad he can't read....

          MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE INFORMATION CONTAINED IN THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED AS PART OF THE SERVICES FOR ANY PURPOSE. ALL SUCH DOCUMENTS AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS HEREBY DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, INCLUDING ALL WARRANTIES AND CONDITIONS OF MERCHANTABILITY, WHETHER EXPRESS, IMPLIED OR STATUTORY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION AVAILABLE FROM THE SERVICES.

          THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED ON THE SERVICES COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN. MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED HEREIN AT ANY TIME.
          LinuxHippie
          • Re: The problem here is...

            [i]He goes as far as stating that "his work appears on a blog that represents the official word from a major development team"

            Too bad he can't read....

            MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS...[/i]


            Yeah, except that exact disclaimer language applies to Microsoft's Knowlede Base, too, in effect making the Knowledge Base equally reliable as the blog. So what's your point?


            :)
            none none
          • Point is.

            You cannot rely on technical information completely. (ie. don't bet your life on it)

            So why make such a big deal and destroy this tester that was trying to help. I can go to any companies KB/blog site and find technical errors like this. If we hung everyone who made a mistake there would be no room for "real" stories.

            That is my point.
            LinuxHippie
          • Blog

            A Blog is a Blog, and if you have all the information there ran by editors, you will stop a good amount of Information that is out there. Because if an editor got involved it would be a KB article not a blog. Now maybe all us tech people should state, hey if you do not understand computers call a buddy that does and refrence this article. But even better a website that knows someone is entering a tech blog warn them on the way in. Either way non tech people will screw up their machine no matter what we do, and I for one would have appreciated that article if I am trying to figure out the IE7 problem. Would not have had a clue it was a registry permission error with the error message IE7 setup was displaying.
            drbasic
    • BLOGS are informal, no-technical writers needed

      I would agree with No_Ax_to_Grind on this as well. BLOGS are informal even at Microsoft, if they were more technical and proofed people would be suspicious of them.

      And really, the example in the article is a bad one. It is clearly a technical article. Not meant to be specific enough for the layman to tackle.

      Any registry changes should be done by people with experience, users should not even attempt it. icrosoft always has disclaimers around this, should the bloger? No I don't think so. He's on the dev team and he's sharing his thoughts, they are not necessarily meant for action by the average layman.

      If someone went in to the registry and were not savy enough to know to check the permissions before overwritting them and making sure that is the problem, probably chucks the instructions out as the first step to building furniture.

      It's a given you mess with the registry, you mess with windows.

      Beta's are to users like flying Airplanes are to people with a drivers license. Attempt it and you might crash.
      rschror
  • Bad advice? Or advice worded in ways that only TECHS understand?

    Big difference and the article's intent is clear: To dumb down the audience rather than trying to make it more learned. That's sad.

    [b]Why[/b] dumb down the audience when we should be smarting them up?! Corporations whine and complain about how dumb the American population is... are they [i]really[/i] so guiltless?

    Or are we supposed to be mindless contented sheep, in which case I'll just watch American Idol and drool brainlessly like everyone else.
    HypnoToad72
    • Good clear writing works for any audience

      I'm not arguing that anything should be "dumbed down." Clear writing will work for any audience. The problem with this particular post from MS is that it isn't clear. It forces the reader to make assumptions, which can be damaging. Contrast it with a KB article, which can be very technical but still works for any audience because the writing is crystal clear.
      Ed Bott
    • Even for a TECH, it's ambiguous

      Clear is not "dumbed down", clear is good English. Clear is communicating with precision - exactly what TECHs claim they want.

      And that blog had the usual ambiguously worded instructions produced by someone who has done it so often that they are running on autopilot ... the problem is that they just say "turn here" and leave it up to the user's own autopilot to flip a coin and decide to turn left or right or maybe make a 180-degree turn.

      I'm a TECH. I'm a TECH WRITER too. (thanks Ed, fir the ego boost!) I make a good living at clarifying instructions like you see in that blog into instructions like the ones you see in the knowledge databases.

      BTW, Ed, on behalf of the profession, thanks for the career boost. :)
      Tsu Dho Nimh
      • I don't think it's ambiguous at all!

        "Clear is not "dumbed down", clear is good English. Clear is communicating with precision - exactly what TECHs claim they want. "

        I read the article and this tech is pretty clear.

        "And that blog had the usual ambiguously worded instructions produced by someone who has done it so often that they are running on autopilot ... the problem is that they just say "turn here" and leave it up to the user's own autopilot to flip a coin and decide to turn left or right or maybe make a 180-degree turn."

        I agree that sometimes techies do the auto-pilot thing or brain dump then don't do a second reading or getsomeone to proof it, but I don't think it is the case here. This person wrote a very concise step by step. However if you started at the step by step part and not read the overview paragraph you might be lost. There's no ambiguity, the instructions rely on the access denied error in the updspapi.log. The so called "choice" that you and the author of the article share, is more of a observation of the techies experience and I quote: "(usually HKEY_CLASSES_ROOT or HKEY_CURRENT_USER)" meaning based on the error in the log file it might be HKCR or HKCU...the one thing he excluded was clarification that the log message will give the full path of the registry key and the user need not "guess" at which one. Hardly something to write a whole ZDNet article on debasting BLOGS from employee's at Microsoft.

        I'm glad you make money at your job, and your good at it, most people are. And no offense when I say; without technical writers we wouldn't have a need for BLOGS.

        Maybe since your a techie as well you could program a Blog ->KB program that can translate a BLOG entry (call it BLOG2KB.exe for nestalgia) and make a living that way.
        rschror
    • I watched American Idol...

      ...& I didn't drool...nor am I a sheep. I may be brainless at times, but I digress...

      I think the point of the article is that, given Microsoft's position in the computer world, which touches most people, a blog entry like this should not be allowed or hosted on a Microsoft site. After all, like it or not, non technical users will take as gospel anything labeled as coming from a Microsoft employee. The fault lies not with the writer, but Microsoft, in that it allows employees to compose technical posts without checking them out. After all, it only affects Microsoft's reputation. (Note: sarcasm in that last sentence)
      rmazzeo
  • Great article

    This is a great article that effectively demonstrates how even informal technical notes can have a significant negative impact on users. With more people turning to the Internet for help with software, it's important that instructions published online be accurate, or a company loses credibility.
    castlem
  • Thinning the herd

    First I hear that coffee may be hot if I spill it on myself, then I read that the inflatable Shamu pool toy I bought for the kid can't be used as a life jacket. Now you're telling me that I may need to possess some technical skills when using beta software????

    When will this madness end? You're right - no one should have personal responsibility for the risks they assume. We need much more hand-holding and such in this day and age. Why should we post a message in the blog asking for clarification from the author? The author should do it all for us, maybe even using Remote Desktop to manipulate the registry for us.
    ejhonda
    • Agreed

      Imagine todays "users" trying to configure DOS 3.0?

      Heaven forbid the "installer" tell a user to edit "config.sys" right?

      If I had a nickel for every time I had to reinstall an OS because I edited something I shouldn't have, I'd have retired at 30.

      I've trashed the win95 and win98 registries more times than I can count. That's how I learned. I made mistakes. If you have it your way, I won't be able to test beta software anymore. It's too dangerous to have on my system.

      At least linux hasn't gotten to the point that the user has zero control over the system. Not that the big distribution developers aren't trying.
      STDog