Yes European Commission, Microsoft’s Documentation Does Suck
April 1, 2006
Although the Brothers have no desire to comment on any specific legal issues between the European Commission and Microsoft they are nonetheless amused by the ongoing statements both parties are making about the quality of Microsoft’s documentation. (Please check the Fine Print for the appropriate disclaimers.)
The short synopsis from the Brother’s perspective is that the Commission has ordered Microsoft to document the protocols used to communicate with Windows server. According to an Associated Press report in the Seattle PI the technical experts for the Commission have stated that the documentation Microsoft has provided is insufficient and inadequate and:
“The improvements required to the documentation are not merely refinements or improvements to the text: The documentation as it stands is unusable.”
The Commission went on to imply that the documentation:
“was written primarily to maximize volume (page count), while minimizing useful information.”
Why the Brothers Find This So Amusing
This dispute over documentation cracks the Brothers up in two ways. First, the Brothers find it funny that the Commission has only now realized Microsoft’s documentation sucks—has the Commission never used a Microsoft product? The Brothers picture the Commission as a Captain Renault like character proclaiming, ‘I’m shocked, shocked to find that there’s no documentation here!’
In fact Microsoft’s documentation has been so historically bad that no one complained too loudly when Microsoft simply stopped shipping manuals with its products. And don’t think for a minute that it stopped shipping manuals because its products are so well designed that users didn’t need manuals. The point is the manuals were so useless that no one really missed them and third parties, such as O’Reilly stepped in to fill in the gap with their ’Missing Manual’ series, which does a better job. There are two interesting side effects of bad product documentation—most users only use about 20% of the features of any product, and because Microsoft trained consumers not to expect manuals the rest of the software industry, or ‘ecosystem’ in Micro-speak stopped including manuals too.
Don’t Be So Paranoid
The second reason that the Brothers crack up at the Commissions position on Microsoft’s documentation is that they are acting like only they, the Commission, gets bad documentation, as if the bad documentation was some personal affront or strategic tactic on Microsoft’s part. It isn’t. Microsoft is just totally incapable of documenting their application programming interfaces, products, and services. The Brothers advice to the Commission: don’t label incompetence as conspiracy—Microsoft’s personnel couldn’t stay up nights working to make its documentation any worse than it already is.
Why is Microsoft’s Documentation So Bad?
The answer is simple economics. Microsoft makes no money on documentation. It just costs them money. They sell lots of Windows and Office to the unwashed computer masses. Hordes of programmers write software for Windows. And all of this happens with really bad documentation.
Even if Microsoft were to spend money to produce better documentation, you have to ask the question, how many more incremental copies of Office or Windows would it sell? Not enough to make back the money spent to improve the documentation. It is equally unlikely that they could charge any more per unit to pay for better documentation.
Decide For Yourself
You don’t have to take the Brothers word for this, consider two examples. To be fair, the first example relates to new technology that is currently in beta, but the current instructions posted at TechNet for configuring the new BitLocker Data Encryption feature of Windows Vista represent documentation that is not only bad, but even following each step exactly can get you into real trouble including losing both data and time. The Brothers have never managed to get the instructions for repartitioning an existing installation to work, and in every instance of trying this procedure they get a ‘file not found error’ at the most critical point and end up with the computer in a state where the only solution is to completely reinstall Windows and try again—a recovery situation that takes several hours. Hopefully by the time Vista ships this will improve.
Searching for Documents Sucks Too
For the second example, consider another common user scenario: you have data in an Access database, and you want to send e-mail to selected records from the database.
The Brothers recently wanted to do this and this case so they started by going to the microsoft.com Web site and searched by entering the following keywords:
access database word mail merge
into the search text box on the home page. One of the results of this search is a document entitled:
Word 2000 Mail Merge Resource Center
Well that looks pretty good, but the version of Office the Brothers have is ‘Office Standard Edition 2003’ (the Brothers are no dinosaurs), so right from the start they have a problem, do these instructions for Word 2000 apply to Word 2003? And maybe there is a newer document, but if they can’t find it what good does it do them.
So the Brothers went to the Office 2003 page of the microsoft.com Web site and entered:
mail merge
in the search text box on this page which finds the following document:
Use mail merge to distribute merged e-mail messages
This document instructs you to how to start mail merge and then use the task panes to get through the process.
So there you go, two examples of Microsoft documentation. If you are really a glutton for punishment try finding and using the documentation to solve the same Access and Word mail-merge scenario using Visual Basic for Applications.
Which ever route you decide to take, the Brothers encourage you to go ahead and take some Microsoft documentation out for a spin. All the Brothers have to say is set aside at least a couple of hours, and good luck.
Meets or Exceeds Industry Standards
Of course Microsoft disputes the Commissions opinion of the documentation, and have offered access to the source code, and technical assistance to help licensees successfully implement the disputed Windows Server communications protocols. Microsoft also provided this quote that is really more depressing than enlightening:
“The comments echo earlier findings of two groups of academic experts from University College London and Technische Universitat in Munich. Those experts independently concluded that the technical documentation Microsoft has created for the European protocol licensing program meets, and in many cases exceeds, industry standards.”
The Brothers call this the ‘Everyone Else Sucks Too’ line of reasoning or just plain excuse. Yes, what we do sucks, but everyone sucks, or sucks more than we do. But the Brothers aren’t buying it. Lots of third parties provide really workable documentation on Microsoft products.
Documentation That Works
The Brothers experience is that to really find out how to use Microsoft products your best bet is to by-pass Microsoft’s documentation, and except for a few cases listed below you should also avoid Microsoft Press books and instead buy books on specific products or technologies from O’Reilly, New Riders, SitePoint, or Apress.
The only books from Microsoft Press that are worthwhile are the Windows internals and programming titles authored by Petzold, Richter, and Soloman and Russinovich. The security titles authored by Howard and LeBlanc, and software process books authored by McCarthey and McConnell are also worthwhile.
Avoid any title from Microsoft Press with ‘Step’ in the title, they are mostly useless reprints of the online or help docs.
And for a really related discussion see the Brothers previous 0xe0000100 blog entry.