Microsoft's MSDN a lesson in how NOT to present important information for your customers.

Go here: http://msdn.microsoft.com/library/default.asp and you try and find information regarding, say, VBSCRIPT's ERR object, and you tell me how easy it is. These people at Microsoft are INSANE. That is the only conclusion I can find.

At first glance one would think that the overall HTML layout is a pretty good choice: a header across the top, a narrow left side "navigation" frame, and a large right side frame for the information you want. However, Microsoft manages to completely ruin it.

First thing you will find is that the navigation frame (their "TOC") is extremely large, extremely redundant HTML (well, XML generated, but HTML in its final presentation to a Browser); HTML that at first is not very large but its size increases as you start "navigating". You will find that initial navigation by clicking in the navigation frame is easy and does not generate much HTTP traffic as at this point the entire TOC has not been loaded (assuming you have started viewing the MSDN Library for the first time). And the Browser caches things nicely.

For example, I navigated the TOC frame and after several ten's of clicks got the tree down to the VBSCRIPT ERR object.

The description of the Err object is a nice overview of the object but lacks completeness. I know it's an object; I want to see it's properties and methods. A couple are mentioned in the text. The text is great if you already have knowledge of this object! But for someone wanting to get a complete reference to the object the information about this object is entirely inadequate. Okay -- so we just have to click another level in the TOC or a link in the description page: Err Object Properties and Methods .

Clicking in the TOC brings up the properties and methods page in the description frame. All well and good as the saying goes. Things get worse from here on in as the saying goes.

At this point the TOC tree has ended and there is a list of links for the properties and methods of the Err object. No descriptions of them, just links. Now clicking on a property link results in a curious thing, we get to the description of the property and then the entire TOC reloads and we suddenly find ourselves very far down in the TOC. So, there is a Book analogy of sorts, we were at a page reading a list of object properties and each property had a reference to a page further down the book to get an actual description of the property. Okay fine. In this case the page was only say, 20 pages away. And the TOC that the browser had to reload had only several more branches expanded*. Well, not too bad. The Browser does have a "Back" button.

So now I read the description of the property I want to learn. And I click several more times to learn about the rest of them.

At this point I (starting form the point where I got to the base Err Object page) I had to click a dozen times to learn about the 5 properties and 2 methods of this object, for the property descriptions are linked together, they are not linked to the methods. All the while for every click the TOC reloads each time. And how Microsoft has implemented the TOC it is not cached**.

What Microsoft has done, is to list consecutively, all objects, then all properties, then all methods (and keywords, functions etc.) for not only the entire VBSCRIPT reference but their entire MSDN reference as a whole.

Instead of listing each object as AN OBJECT! with all of it's properties and methods, for each object, they have linearized their entire database!

And what makes things worse is that each time you want to read the description of something you must load just that one something (property, method, etc.) and at the same time the entire TOC!***.

There is no "next" button in the content of an object, i.e. go to the next description of the next property, you can not navigate a single object as a single object! You can only "move" from next to next for all properties or all methods. This lineararity works within a single context only; all statements, all constants, all events, and all properties of a object for each object. It is horrible that they linearize on all properties for all objects. Compounded by the fact that they have a single page for each property, method, etc.

Now, VBSCRIPT has five objects with a total of 11 properties and 7 methods. So it actually ain't too bad. However, the references for Excel.Application or Word.Application objects are far more complex with hundreds of properties and methods.

It takes hours to navigate MSDN. Hours. Hours.

Fully, 90% of my time programming for Microsoft Office is spent navigating MSDN (and Googling). The tops of their reference tree for all of their objects are slight overviews only, with simplistic, useless examples that show only one or two properties or methods. There is no complete set of links all in one place for any one Office Object.

MSDN is a horrible, horrible quagmire of twisty little passages all alike. There is no wonder whatsoever as to why people say that Microsoft Sucks. MSDN is an example of either design by compartmentalized committees, planned obsolescence, or stupidity. I actually believe that it is a combination of all three, with most of the problem based on the sickness of "getting people to buy CDROMS and BOOKS" to try to get better programming references. However, have you ever read a popular book about Microsoft Programming? They too are horrible. Every book about Microsoft Programming that I have ever purchased or seen -- with the exception of O'reilly's VBSCRIPT reference -- has been as poorly presented as MSDN with the addition of being never complete and having lame examples.

I have come to the conclusion over the last several years that Microsoft's programming languages, VBS, ASP, along with COM and the DOM, are actually VERY GOOD THINGS. PHP and Perl also integrate well into this model. HOWEVER. The Documentation SUCKS COMPLETELY!