MSDN Documentation – the worst in class ?

Did it ever happened to you that you were using some tool day after day – and never realized it’s pretty big deficiencies ? Until somebody, coming from different background pointed out what everything is wrong with the tool ? Before that moment of revelation, the issues were just inconvenience, but right after that they became real annoyance ?

Exactly this happened to me last week and the credit for pointing out what is wrong with MSDN documentation (and the “standard” .NET documentation format in general) goes to Joel 🙂

For developer using object oriented language such as C#, Java or Ruby, what you need on daily basis is to find information about a class, see its public interface,members, constructors, method signatures. Ideally, on single page, with possibility of drilling down to the details of a method and to a code example. You also very often need to see all implemented interfaces, have easy access to parent class and (in case of e.g. an interface inside a framework) to access the implementing classes or derived classes within this context.

Unfortunately, the Microsoft .NET documentation makes this simple task not exactly easy, pleasant or fast. As an example, lets take something really simple e.g. DateTime struct. In the documentation, information about this simple class are separated to 6 pages: datetime structure itself, Members, Fields, Constructor, Methods and Properties. If you would expect that with this devotion of low level categorization the particular page for e.g. Methods will give you all details about all DateTime methods, you are wrong. What Methods page gives you is just list of names, not even a method signatures – parameter types and return values are missing. To get this information, you must click through into the page dedicated to that method. If the method is overloaded (take e.g. omnipresent ToString), the Methods page contains only one name and only the next page gives you the signatures, linked to another page with details. See for yourself

In addition to bad information structuring, almost every link causes full page reload.

Compare with how much more usable is the Java documentation: it is very easy to see all interfaces, methods, constants, parent classes, implemented interfaces in single page. The dated frames-based UI actually makes lots of sense and is (except AJAX based dynamic site) much better way how navigate the documentation.

With all that said, I am not surprised that the tools such as Reflector are so extremely popular in .NET world. It not only provides very useful debugging/inspection tool, but thanks to excellent and compact presentation of information about the class retrieved from reflection, they are the fastest way how to get meaningful information on core classes API. Other than Reflector, the other fast way how to get information on .NET core library details is Google search.

Try for example how fast you can access a documentation for particular class starting with Google search – let’s take e.g. WebConfigurationManager. Google search returns blazingly fast (as always) – with the MSDN page as first hit. Now compare how fast you will get the same information starting from MSDN home page, (which is btw, advertising ‘new and improved search and navigation‘). Your mileage may vary, but I usually see 3-8 seconds delay in search response (compare to <0.5 sec for Google). Few seconds seems like no problem, but when you do it all the time, it easily becomes pretty annoying. Even more so when you realize that Google is searching WHOLE WEB, with content they do not own or control, only index and rank, whereas MSDN search is searching MSDN data repository, which is – however you measure it – by many orders of magnitudes smaller and Microsoft fully controls most of it’s content.

Why cannot the largest and most powerful software company create documentation that is useful and usable ? Even the documentation for the OpenSource Mono project (port of .NET to Linux and other platforms) is *much* better than the original. See the class DateTime there for comparison: the menu is dynamic and does not reload page every time you click on a link, the methods have full signatures and everything is on single page with local links and only details are on second level page.