I don’t like MSDN

I’ve long held that Microsoft could do better with its developer-focused sites. It isn’t a topic I’m likely to let up on, but today I wanted to look at a specific example.

I was reading the PostgreSQL documentation on the ALTER INDEX command, and was generally pleased with everything about it. Its easy to read, informative, quick to load, and usable. Here’s a screenshot of the page as it first appears (or you can go there yourself at http://www.postgresql.org/docs/8.1/interactive/sql-alterindex.html):

The MSDN page for ALTER INDEX loads up looking like (or you can go there yourself at http://msdn.microsoft.com/en-us/library/ms188388.aspx):

Maybe its just me (is it?) but for me, the difference is night and day. I can put aside the poor color choice, and weird (and branded) search bar, and the overwhelming amount of navigation (actually, I find this quite annoying), but there are some fundamental things that make MSDN a pain to use.

Some observations:

  • The MSDN breadcrumb is 12 levels deep, two lines, and each item brings up its own popup navigation. The PostgreSQL one is 4 levels deep and is plain.
  • The MSDN has a Printer Friendly Version, the PostgreSQL one IS printer friendly.
  • MSDN’s left-hand navigation is useless – it’s too big, too nested and uses up too much room
  • The MSDN page took 46 requests, 226.5KB and took 5.44seconds to load for me. The PostgreSQL page took 16 requests, 21.3KB and took 1.46seconds to load
  • The MSDN page hits 8 domains (including webtrends). The PostgreSQL page hits 2 domains (including google analytics)
  • The MSDN page has a cryptic URL. The PostgreSQL has a human-readable url
  • The MSDN page allows you to lookup other versions via a box in the middle. The PostgreSQL lets you change the URL.
  • The MSDN page scores 67 on Yslow, PostgreSQL scores 76.
  • The MSDN page is inconsistent about cross linking other topics, sometimes CREATE TABLE is linked and sometimes it isn’t. CREATE INDEX though is never linked. The PostgreSQL documentation is more consistent.
  • Searching “Create Table” on MSDN brings up the SQL Server 2000 documentation (with no way to get to 2008). Searching “Create Table” on PostgreSQL brings up exactly what you want. (Both sites display search results poorly)
  • MSDN’s Titles don’t include the version, so the 2005 and 2008 titles are the same (which means your bookmarks will be the same). PostgreSQL has stupid long titles, but at least the version is there
  • The MSDN text is small and tight and ends up looking like a wall of text. The PostgreSQL looks like its meant for a human.

A note about the version selection. The MSDN approach may be more intuitive, but it appears limited to going from SQL Server 2008 to 2005, there’s no way to go the other way around, and no way to pick an older database. With PostgreSQL you can change the url for any minor version starting at 7.1.

Of course, when everything’s said and done, despite all the small things (like # of dns lookups), the end result is that one is a mess, while the other isn’t.

MSDN’s Lightweight and ScriptFree are definitely a step in the right direction – but this choice clearly falls in Barry Schwartz’s Choice is Bad For Us point of view – something a lot of people at Microsoft need to desperately be made aware of. I actually like ScriptFree, and it addresses a number of the above problems, but not enough and in the end it still lags behind PostgreSQL’s usability. I mean, why is the ridiculous syntax the first thing even displayed? Why do I still see a wall of text, and who actually thinks that because I’m reading up on ALTER INDEX, I’m interested in a bunch of truncated links to other ALTER statements?

This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.

28 Responses to I don’t like MSDN

  1. Bill Gates says:

    Thanks for your input. I am considering buying PostgreSQL and promptly shutting it down just to spite you.

  2. Ely says:

    Wow, seems you are really digging deep for something to complain about. Maybe a little less complaining and a bit more contributing will bring Codebetter.com back to its former glory.

  3. mielniczuk says:

    Great to see usability discussions entering dev documentation area. An easier to read, more intuitive site or page is more likely to encourage repeat visits and greater participation.

    MSDN has been around for a long time. The look is dated, but it is familiar to many of us. Changes to legacy systems are sure to stir controversy. Nonetheless, it may be time to consider it.

  4. Dave Cluderay says:

    The left-hand navigation on MSDN is definitely too deeply nested to be useful these days.

    I’m pretty confident that people will typically only use that mechanism for navigating around items at the same level in the documentation or perhaps to items at the level immediately above and below in the hierarchy.

    Displaying the complete hierarchy pushes the interesting stuff further and further out to the right of that pane making the user experience pretty underwhelming.

    They could improve the experience by presenting a more contextual slice of the overall TOC by default (with the option of expanding it to a full hierarchy for those people that, for whatever reason, need it).

  5. Speednet says:

    Maybe they keep MSDN huge, messy, and confusing to keep book sales strong. When I hear people say “Why buys books, everything is online” it makes me laugh. This blog is harsh, but completely accurate.

    I can’t stand the dreaded left navigation (you might want to change “right” to “left” in your blog). It makes me shudder to see a tiny bit of text peeking out in the screen capture, because that’s what you ALWAYS see when you go to that site.

    I use the tree control maybe 1% of the time — but the other 99% of the time I have to live with that stupid thing taking up valuable screen space, and when I want to see the labels I always have to expand the size, scroll it, etc. It is the absolute worst design for the web.

    Within the past few months Microsoft revamped the look and colors — why didn’t they put some good navigation in there and drop-kick the tree control? I guess the gearheads who designed it really like their work. Maybe get the Office team to design the site.

  6. karl says:

    @Abdu:
    Agree that fast backward/fast foward seem useless (although they appear to be the only two which are). And you can add

    @Mark:
    You can post comments to the lastest versions of postgresql (dunno why you can’t post to older stuff). Both sites are lacking in support for “community contributions” though as far as I’m concerned.

    Also, you can’t navigate from 2005 –> 2008, which is annoying. And the search often pulls up 2000 entries. So the support story has some holes in it.

    As for navigation,I bet most people just google search for other topics (i know i do), so all that extra navigation on MSDN is just noise. But if you use it, I can see how useful it is.

  7. @Anis Ibrahim
    If you don’t like Karl or Ayende’s opinions, then stop reading their blogs. It is after all, *their* blog and fully within their rights to post about whatever they want, including their honest options about why the do/don’t like something like MSDN. Simple.

  8. karl says:

    A lot of you missed it, but I did talk about Lightweight and ScriptFree in the very last paragraph.

    and I fixed the postgresql link, thanks.

  9. webflo says:

    Did you try to change the display layout by using one offer by the MSDN site ?
    You change choose between different style. One of them may be good for you: ScriptFree
    http://msdn.microsoft.com/en-us/library/ms188388(loband).aspx

  10. Anis Ibrahim says:

    “I don’t like MSDN” – Who cares about you ? Are you some legend that your views should heard?

    An unasked advice : Break down your ego and stop reading from people like ayende, it makes you rude and unruly!

  11. Mark Brackett says:

    1. The PostgreSQL link is for REINDEX – not ALTER INDEX. I’ll compare the relevant ALTER INDEX sections (http://www.postgresql.org/docs/8.4/static/sql-alterindex.html) for the rest.

    2. Sql Server’s ALTER INDEX is way more powerful than PostgreSQL’s. That naturally leads to more text and explanation.

    3. MSDN has the nice tree on the left that allows you to hit whatever T-SQL command you want. For PostgreSQL, you need to click the PostgreSQL 8.4 link, then read through the index and find SQL Commands. At which point you get the list of SQL Commands. It’s about 3 or 4 more clicks and a lot of reading to get the list of operators, another link for data types, etc. In the end, I’d say PostgreSQL reads more like a book or a manual that expects to be read sequnetially, and MSDN more like a reference (which depends on a comprehensive and detailed index to be useful). To be fair, PostgreSQL does have an index and it is comprehensive…less than great UX though, as you have to scroll all the way through to find varchar.

    4. I actually *like* the structured grammar in T-SQL’s syntax. It’s about the only way you can actually make sense of some of the options. Yes, it’s complicated – but so is T-SQL. I haven’t seen a better way of presenting the 1000+ permutations of ALTER INDEX. PostgreSQL gets a pass, since it’s a lot simpler.

    5. PostgreSQL recommends reading CREATE INDEX for the available parameters. That’s a cop-out.

    6. MSDN links to more info on some topics, like Partitioned Tables and Indexes, Recovery Models, etc. PostgreSQL just links SQL commands (which are easily found on the MSDN tree) and expects you to know what an “index-method-specific storage parameter” is.

    7. MSDN is a *lot* more informative, has more complete examples, and even accepts community content.

    8. SQL Server 2005 and 2008 are the only supported versions of SQL Server right now. I think it’s acceptable to not link SQL 2000/7/6.5/etc. They’re still findable (hint: use the breadcrumbs).

    9. Yes, MSDN is slower. I tend to have broadband and decent HW when working with SQL Server, so I don’t particularly care. But, yes – I agree it can be a PITA some days.

  12. Abdu says:

    – On MSDN, I like the different background color for examples and other sections. I can quickly glance at them. PostgreSQL is all plain white.

    – You can add feedback at MSDN. PostgreSQL you can’t.

    – While the left nav bar, might take a lot of space, you can drag it out of the way. Personally I like a button that does it instead of doing a drag.

    -MSDN should refresh content using Ajax instead of a complete page refresh.

    – What is “Fast Forward” & “Fast Backward” on PostgreSQL? I have no idea where they go and the breadcrumb doesn’t change. It’s always at PostgreSQL. Pretty useless.

  13. dave-ilsw says:

    Minor nit: The PostgreSQL link you provided in your writeup is for reindex, not alter index.

  14. Andrew says:

    More important than anything you brought up is simply that many of the MSDN entries show you the completely wrong way to do something. True, developers should be smart enough to realize that, but when it comes from the mothership, more often than not complete code examples will just be copied into the code without a second thought.

    See the following for a great example on this:

    http://msdn.microsoft.com/en-us/library/ms734681.aspx

    Notice that the bug was pointed out in 2008. I know this MSDN article very well because one of my lazier developers used this in his code causing no ends of trouble.

    If MSDN had good articles (not ridiculous hacks or work arounds) it’d be worth the silly navigation and the brutal load times.

  15. @John, +1 to reading the last paragraph. Karl clearly states that he *has* used them and that they are improvements. The problem there is having a choice at all. This is definitely a case where there is a clear “better” choice, and that should be the only option.

  16. Danijel Ilievski says:

    I strongly agree with you about the poor color choice for code examples and snippets. Why don’t they use color scheme as editors in Visual Studio, SQL Server management studio, etc?

  17. John Sheehan says:

    Ernst, you should read that last paragraph more closely (or read it for the first time).

  18. Darren Kopp says:

    @Ernst

    Doesn’t have to have lightweight in the URL. It will use cookie to remember what your preference was.

    I should also add, i use the lightweight version, not the classic version.

  19. Hi,

    You obviously didn’t click the “Lightweight Beta” button, seen in the top-right of your screenshot. Or, alternatively, go there yourself: http://msdn.microsoft.com/en-us/library/ms188388(lightweight).aspx

    ;o)

  20. Sean says:

    Switch to the lightweight mode and check out the following page: http://msdn.microsoft.com/en-us/library/system.threading.threadpool.aspx

    I haven’t used the classic view (the view you’re using) in a couple of years.

  21. ktmt says:

    Agree completely. I go to MSDN last. Another thing I really dislike are all the links I have to click to get to subtopics. Some times they lead in a circle, other times I’m just led down a never-ending chain. Either way, I nearly always get so lost as to where I’m at that the information I might gain becomes nearly useless. I’d really like to see MSDN consolidate topics into fewer single articles.

  22. Darren Kopp says:

    Ok, lets go through this point by point, and i’ll give you my not so humble opinion. You already get my opinion on the yslow part and i feel it irrelevant in the context of this post.

    1. The breadcrumb is due to the fact that the entire MSDN library is in here, and this topic is a subleaf of it. I *never* use the breadcrumbs because they are useless, and i find the left bar navigation MUCH more useful.

    2. Having a separate page for printing doesn’t bother me because i never print. at best, i would save the printer friendly version into pdf. so again, doesn’t affect me (and for god sakes man, save the trees!, don’t print!)

    3. The left hand navigation IS useful, but only so when the focus is correct. browsing through the namespace is great, and it makes sense. in t-sql, it’s a bit more hard. The issue here is that again, the entire library is in that left tree. Collapse the scope to the product at hand and issue is probably solved.

    4. Speed doesn’t bother me as long as the quality is good, and solves my problem. in your example, you don’t really say whether you got enough information or not, so it may or may not affect you.

    5. MSDN has been around a while, and it MAY have a non-cryptic url. T-SQL doesn’t really lend itself as easily to human friendly urls in this case, being in a very large library like msdn, but msdn DOES have user friendly urls (ie. http://msdn.microsoft.com/en-us/library/system.threading.threadpool.aspx). That same page also has a cryptic url, and the issue at hand here is they should always redirect to the friendly url, if there is one.

    6. As long as you can change the version, it doesn’t bother me. Not everyone knows how to hack the URL either, so I’m not really bothered unless you weren’t able to change the version.

    7. *snip*

    8. Should be fixed, but to an extent, pages like this would have too many links if every page was linked. I’m a huge proponent of search driven UI, because that’s how i operate. not everyones style though.

    9. They should implement documentation versioning like they do in .net framework, where you have 1 topic page linked by search, but you can jump between versions.

    10. For the reason in 9, i don’t think the version should be in the title. you are looking at a concept, not the version. for the most part, those concepts won’t vary drastically between versions, so you should be able to just jump between them.

    11. Browsers have nice ways of zooming. Some people like small text, some like large.

    To give MSDN and Microsoft credit, for the amount of software they have, their documentation is actually quite good compared to most all other products. sure, some may have better documentation in some areas, but overall, they have done a nice job.

  23. Bunter says:

    For me MSDN turned into slow unusable mess years ago. Usually I can find what I need from google way faster and I totally agree many MSDN sections are more readable by robots from outer space than humans. They seem to have especially hard time documenting more recent API-s. I can understand they need to translate all this stuff, but 1 good english documentation is way better than 30 useless localized versions.

  24. All microsoft site suffer from zero version logic. If you look at any of their pages you can never tell if the tool is the most recent version.

    Just today I was looking to update windows installer, a google of this take you to windows installer 3. However the latest is 4.5, but it doesn’t say this anywhere on the page.

    How easy would it be to put a alert at the top of the page saying that there is a newer version.

  25. karl says:

    Darren: About MSDN being this huge multipurpose thing – its an true, but its an excuse, and its solvable. In the end, it puts the burden on the user.

    I can’t stand the design/look/code/layout of codebetter.com. I don’t own the site. I contribute. But I have made my opinion known about it as well.

    I find it dumb that http://www.asp.net has ads on it, but I find it dumber that people think I can’t have that opinion because codebetter has ads on it.

  26. J.R. Garcia says:

    @Darren Kopp I see your point about MSDN having ALL documentation included, but why wouldn’t they separate the documentation? It just adds a bunch of noise to the site.

    In regards to Karl pointing out the difference in yslow grades, at what point does he “bitch”? At the top it says “Some observations:” and he just gives the scores. Nothing more.

  27. Darren Kopp says:

    btw, you get a 57 yslow rating, making this site unusable, also making the content unusable right?

  28. Darren Kopp says:

    Postgres is documentation for a database. MSDN is documentation for ALL microsoft developer material.

    Also, you are really bitching about a 9 point difference in yslow?