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

picture-2.png

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.

Advertisements
Explore posts in the same categories: ASP.NET, csharp, dotnet, Java, OpenSource

11 Comments on “MSDN Documentation – the worst in class ?”

  1. Darren Parker Says:

    Thanks for the great feedback Miro!
    We are continually looking at ways we can improve the documentation that we produce.
    I have forwarded this onto my fellow team members who are hard at work planning the next design changes for our documentation.

    Darren Parker
    Developer Division
    Microsoft

  2. Anand RAman Says:

    Miro,
    My team is working on a document design to address your concerns. I will talk to MSDN team about the performance issues.

    Anand..

  3. Hans-Juergen Philippi Says:

    Another inconvenience you didn’t mention: Highlight a keyword in Visual Studio, press [F1] and wait ages for the MS Document Explorer alone to display the matching help page. I’ve seen this taking up to ~30 seconds, I guess, on my not too outdated Dell Centrino Laptop with 1 GB RAM.

    That fact that you point out frame based HTML help systems that are made better pours oil into the fire that started when some self-appointed usability gurus claimed frames in HTML pages to be evil. I always found and still find them extremely useful, if dosed well, and the fact that the AJAX hype with all its bells and whistles celebrates partial page loading/rendering as the holy grail of Web 2.0 GUI design just makes me smile: Welcome back, (i)frames! 🙂

  4. Patrick Says:

    I partially agree wwith you, Miro.
    I *MUCHLY* prefer the Mono documentation style over the awful Javadoc, though.
    Having an overview over all constructors, methods, fields, properties, and constants on a single page is great. I also never understood why method signatures aren’t included in the MSDN docs.
    Nevertheless I prefer separate details pages over a monolithic document – even if only for aesthetic reasons.

    Cheers,
    Pat

  5. Miro Says:

    Hans-Juergen: same experience wrt to the built-in Help speed on my side. It is not 30 sec, more like 10-15 sec – on Dual Core AMD, 2GB RAM, XP. So I guess throwing more CPU on it does not quite help …

    As for frames – you see them a lot outside of Java – check Ruby documentation.

    Patrick: I am not too crazy about Javadoc – it is old, looks quite ugly – but it gives you all important information at the starting page. Mono team did the great job in that aspect too and it looks much nicer. My main issue with Mono is that – as I do develop for .Net, not for Mono, I do not feel comfortable using it as main source of information for the “official” .Net implementation. There are differences between these implementations. If MSDN team would adopt the Mono style/Mono tools are re-generate the .NET docs, that would be awesome !

    The question whether single page (with in-page anchors) or multiple pages – it all comes to user experience and proper division what is where, how do you navigate to the information and how you come back. It is also important what is the impact of loading one large page once versus hitting the server for detail pages multiple times.
    Combination of Frames and in-page anchors works very well for me – but YMMV 😉

  6. Rob Relyea Says:

    Check out XamlT (http://XamlT.com) …an experiment I did to help visualize class hierarchy information. This visualization of hierarchy has a very dense information display…I’ve only spent a week or so working on it, so I’m sure it could much farther as other people try this sort of thing.
    It is a WPF application which visualizes the hierarchy, when you press F8 (or click on the SDK button in the toolbar), it will jump to MSDN content for the current Type…but it doesn’t display it in a frameset…and the data is dynamically converted from XHTML to a great flow document in XamlT…like the New York Times Reader…

    Thanks, Rob

    Rob Relyea | Program Manager, WPF & Xaml Language Team
    robrelyea.com | /blog | /wpf | /xaml

  7. cocotapioca Says:

    There is no better documentation that clear and well wrote code(and with some useful comments). See the some smalltalk implementation, like Squeak. The code of the whole system is there for you to see. What does this methods? just lets see the code. And the programming environment is better to, better refactoring, better organization of the code (organization in files is not the problem, the problem is the visualization actually). I’m a smalltalk fan but i work with .net a vs.net at my work, and is a nice framework, powerful, and i enjoy using it, but there are lack of things.

    MSDN Documentation sucks.

  8. MattMc3 Says:

    I’m really glad you mentioned Reflector, because its simple “Class Browser” style interface is *exactly* what I wish MSDN was like. In fact, if the “Class Browser” in Visual Studio showed doc comments and behaved more like Reflector, I’d never need to leave the IDE.

    And, as an added bonus, the ability to decompile my assemblies and look at the generated code in a host of languages makes Reflector the most valuable .NET utility I use. It’s super handy if you’re a Boo aficionado like myself and want to see what sort of C# code is equivalent to what you just compiled in Boo. Microsoft should take note.

  9. Joel Says:

    Wow… I didn’t realize my rants were such good blog fodder. I should start my own.

    Have I told you how much I hate the Collections in .Net. It up there with how much I hate the Java Calendaring API. Why doesn’t IList define sort? Or maybe SortedList should implement IList as well. Who wrote this stuff?

  10. anonymous Says:

    I agree that the MSDN documentation is a huge time burner. I develop in Flex most of the time, and moving to do some WPF development, I’ve found learning to be time consuming because I don’t have a handy reference.

    Adobe has an awesome class browser for Flex, that despite problems that all of them have (code out of data, not enough comments/examples, errors), it does allow for seeing all the members quickly and get a feel for a class in no time.

    For comparison:

    http://livedocs.adobe.com/flex/201/langref/index.html

    Flex with mxml/AS3 and WPF with xaml/C# seem to be much the same thing. With how much of my day is spent reading documentaiton to do new things, having a leg up there would make me markedly more productive.

  11. Jamie Says:

    As an Eclipse Java developer now learning C# and Visual Studio, I really understand your pain.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: