MSDN Library: A Discerning Comment RRS feed

  • General discussion

  • There is something that's really bothering me for quite a while now when reading the MSDN library... I don't know if other users share the same problems I have but I believe it's time to ring the bell now...

    I'm using MSDN Library as my primary source for learning Microsoft technologies. When reading through topics to get a thorough knowledge of an area, there is one thing that's really keeping me from learning effectively: It's the excessive use of Teaser Hyperlinking in MSDN.

    Perhaps I'm different from other users... In early times I bought a book to learn things. Back then, I knew where to start and I knew I learned it all when I'd reached the end. I remember reading and working through the whole "The Waite Group's Windows API Bible" in three months... I still remember most of the API... But nowadays there is virtually no end to a topic. There is never a "you know all of that topic now" situation.

    What's particularly annoying me is this kind of teasing "did you know?" kind of notes spreaded throughout the library. Here's just one:

    Note A second XML Web Service, called Customer Data Service, allows you to upload, download, and manage custom data sources, including points-of-interest and polygon data. For more information, see Introducing Customer Data Service.

    Fearing to maybe missing an important topic I follow those teasers... You never know if you will tumble over that probably important information ever again.. It's impossible to foresee where these teasers lead to. Sometimes it's just the topic right ahead which you would have reached anyway, sometimes it's completely elsewhere...

    Sometimes, after I follow those teasing hyperlinks, read their content and find its information non-useful, if I manage to return to my original topic from where I left, I have completely forgotten why I was reading the original topic at all...

    Why can't a page just restrict its contents to its contents? No teasing, no hyperlinking... except for class, member function, field etc. reference Hyperlinks... Just no more Hyperlinks to tutorial information. - Put these teasers into separate Overview pages and keep them there.

    Which brings me to the second thing bothering me: As a user you never know the full extent of a topic until you have unfolded each and every single sub node in the TreeView to the left of MSDN Library Online. Even more, when you start reading you come across Overview pages like this which contain other Overview pages which again contain other Overview pages ...

    I honestly like and encourage a good structure. But this way I believe this is plain information hiding... But more than that I believe it's keeping the reader from structured learning.

    Why doesn't MSDN Library use only one single Overview page for each encapsulated topic, displaying the content of all current child Overview pages as a hierarchical list and omit all these child Overview pages then? It's completely sufficient to have one single table of contents. A TOC should be complete and exhaustive.

    Perhaps I'm too old-fashioned... I'm overwhelmed by this current kind of structure, containing many bits and pieces instead of a single, forward, self-contained topic structure.

    I'd like MSDN Library to return to a transparent, more book-like kind of structure:
    • Hierarchical Table of Contents,
    • no sub Overview pages,
    • no more unobjective "unrivalled", "excellent", "better than ever" kind of comments,
    • a topic's content pages giving you the good "I now know it all" feeling after reading them, thus...
    • no teasers,
    • a page's content being complete and self-contained, referencing (hyperlinking) only reference content, just like an index used to do in a book... back at those days...


    Wednesday, November 25, 2009 7:28 PM

All replies

  • In the context of my above comment I'd like to add that it would be very feasible to have kind of a hierarchical numbering system added to MSDN Library Online Help articles spreading several pages.

    This way it would be easier to see if a Hyperlink referenced content from a page ...

    • preceding the current page in the context of the current article
    • following the current page in the context of the current article
    • pointing to content not related to the current article at all.

    This would also help estimate the importance of the referenced content in regard to the information on the current page.

    So a typical TOC would read like this:

      1.  Online Services
        1.1  Windows Azure Platform
        1.2  Bing Services
          1.2.1  Bing API
          1.2.2  Bing Maps SDKs
    Bing Maps AJAX Control SDK
    Tuesday, February 9, 2010 6:03 PM