MSDN Documentation – the follow up

Judging by the number of hits, Joel (and myself) are not the only people who would like to see nicer, better and faster MSDN documentation. As a very nice surprise, some of the feedback came directly from the people than actually can do something about it – like Darren Parker from Microsoft and Anand Raman from the Sandcastle project. Rob Relyea suggested and interesting looking tool based on XAML.

Thanks everybody – it is always nice to find out that even really big companies listen to the developers and want to address the problems. It almost feels like OpenSource experience where (it was few years back) we have encountered an issue in one of many Java templating libraries, posted to discussion group a question and few hours + several emails later had patch for the bug from the library creator :-). But back to the topic.

In addition to the issues mentioned yesterday, I’d like to add few more suggestions:

1) Multiple languages on the same page.

In theory, it sounds great to be able to select in which .NET language syntax I want to see the class, but …. In real life, we seldom switch languages. The project that starts as C# projects will stay C# project – and for several months the developers will not care about documentation in anything but C#, certainly not J# or Javascript … For that reason, ability to dynamically switch languages is not really important. And who needs J#, anyway 😉 ? If there is one thing that should go to sub-pages, the “other languages” should be it.

2) Visual organization

Sounds like minor problem, but it impacts usability a lot. Few examples: The icons in the first column can be safely dropped and free space better used to add the return type and parameters. Position in the inheritance tree and list of parent classes / implemented interfaces (hyperlinked) should follow. After that, the list of members – constructors, methods, properties etc, preferably in single page with links to detail page / code examples. Just compare the definition of DataSet in Mono documentation and in MSDN to see the difference.

3) Postback behaviour

Frames are old and out of fashion, but IMHO still best solution for some sort of tasks – such as documentation. One of killer features of frames is separate and independent reload of one frame while others keep the selection, scroll position etc. Why does the MSDN page – which uses frames – have to reload all of them ?

4) URL’s

In the spirit of REST, the URL should be descriptive and understandable. The MSDN URL’s are not bad – take for example

http://msdn2.microsoft.com/
en-us/library/system.data.dataset(vs.80).aspx.

I am not sure, however, what value adds embedding the VS version into URL. It may be sometimes interesting to see the changes between the 1.1 and 2.0 versions of the same class, but it would be cleaner to make the “split” at the top level ( e.g.

http://msdn2.microsoft.com/
en-us/library/2_0/system.data.dataset.aspx

) and provide link from the 2.0 version of DataSet documentation to 1.1 / 1.0 version of the DataSet documentation. This is immensely usefull if you are porting the 1.1 application and need quickly review the changes.

4) Breadcrumbs or Dynamic Menu or what the heck it is

I mean this:

picture-3.png

This is something that really should be reviewed, both from implementation and well as content perspective. As I see it – it tries to be several things at the same time and does not really do properly any of them. It duplicates part of the path in tree in left frame, interwoven with some other information.

Some members of this construct are just plain confusing – for example Previous Version. Assume that I am on DataSet documentation and Click on Previous versions, it lands me either on starting page for .NET Framework 2.0 or 1.1 implementation. The problem is that NONE of these pages has anything to do with page I was on – the DataSet – and only way how to get back is Back button …

From usability perspective, selection in the “menu” often causes postback and redraw of all frames …

One more thing: it is not really important (and it may not be a problem on Microsoft side), but the left-side tree does not load in Safari on Mac – not that there would be too many people reading MSDN documentation from OS-X platform 😉

picture-4.png

Advertisements

2 Responses to MSDN Documentation – the follow up

  1. Anand Raman says:

    Please look for a blog at http://blogs.msdn.com/sandcastle about the new deign we are working on. This new design code named “VS Orcas” will address most of your design concerns (http://blogs.msdn.com/sandcastle/archive/2007/06/15/net-document-design-and-msdn-documentation.aspx).

    In addition I spoke to MSDN’s development manager, Kim, about the performance issues and ponited her to your previous article. She mentioned the following:

    The TOC in the library is the major performance killer. Some are as large as 1M. With July MSDN release the size will shrink dramatically. They’ve moved away from using the standard ASP.Net deep-tree to a more custom one. The standard one uses tables; custom one will be using divs.

    The size is a definite improvement. At the same time, they are changing it to an AJAX implementation with client-side caching to pull each TOC chunk as an independent request. Hopefully this will help our customer experience.

    Microsoft definately cares about our customers help experience. Cheers.

    Anand..
    Group Manager
    Developer Division
    Microsoft Corporation
    http://blogs.msdn.com/sandcastle

  2. Joel says:

    Yeah I hate the mutliple language things as well. But I have heard people say they like it because they can see the same code implemented in different languages. So it becomes a bit of a learning tool.

    I really like the example code in the MSDN documentation. That being said I don’t like that most of the example code is the same snippet regardless of what parts of a class you are currently browsing. This results in pages having examples that don’t really exemplify the methods you are trying to use.

%d bloggers like this: