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.
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 ?
In the spirit of REST, the URL should be descriptive and understandable. The MSDN URL's are not bad - take for example
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.
) 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:
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 ;-)
Author Miro Adamy
License (c) 2006-2020 Miro Adamy