This week, we made some progress on reorganizing the developer center and we had some great discussions with developers about what is and isn't working with MSDN documentation.

Upcoming Updates to the Learn Tab content

From a post earlier this week...

The following is an intermediate revision to the TOC, there will be more to come as we keep getting better at this!

+Windows Development Learning Topics
  +Learn Windows by Feature (not yet published)
      - Learn about Windows animation manager
      - Learn about Windows Graphics
      - Learn About Libraries
      - Learn about Sensor and Location
      - Learn about Windows 7 Taskbar
      - Learn about Windows 7: Touch
      - Learn about Windows Ribbon
  +Learn the developer fundamentals for Windows (not published yet)
      - Accessibility
      - Learn about Windows Web Services
      - Windows Core and File Development
      - Windows Graphics
      - Windows Networking
      - Windows Multimedia
      - Windows Power Management
      - Windows Security
  +Solutions (not published yet)
      - Learn how to write a Windows application with Hilo
      - Learn to Progrtam for Windows in C++
      - Learn About .NET Framework Development
      - Learn About HTML Development
      - Learn About Win32/COM Development
      - Learn about Windows 7: Overview
      - Windows Graphics How-tos
      - Windows Networking How-tos
      - Windows Security How-Tos
      - Windows User Interface How-Tos
      - Facebook SDK Overview
  +TYPE (no page created yet????)
      - Books for Windows Developers
      - Browse Windows Code Samples
      - Browse Windows Programming How To's
      - Browse Windows Videos
      - C++ Videos for Visual Studio 2010
      - Windows 7: “How Do I?” Videos

The real goal of this reorganization is to make it more clear what sort of content you will encounter while browsing through the learn content on the developer center.  For example, when you click on the Learn by Feature section, all of the features that we have learning paths for will be made available.

Discussions with Developers about MSDN as a learning tool

In some talks with (real, actual, Windows) developers that I had earlier this week I was reminded of a common dilemma that developers face when developing for Windows: 

It's really hard to find the guidance documentation but it's really easy to find the reference documentation - as a result, despite the guidance being what devs want, the reference is what they always find.

I'll dive a little deeper into this today but next week I'll follow up with more details and more thinking that I have had about this, how we can fix it, and what we can do until we have a solution.  At the heart of the problem is the reality that the bulk of the documentation on MSDN is reference.  This is an artifact of what programming writers know closely as the consent decree - the result of the DOJ lawsuit that mandated that all public facing code be documented to level the playing field for Microsoft's platforms.  I wrote an article on this a while back but the short version is that we have a policy to at a minimum document every interface, method, property and so on for every piece of code that ships. This results in a significant number of pages that are placed on MSDN and also distracts from the more useful guidance documentation.

Related to this dilemma is that developers don't know how we're organizing our documentation.  There is a Redmond RDF that writers have  - don't the developers know that there's a programming guide in addition to the reference? The answer being of course not! It's not the developer's fault either, it's ours.  We don't clearly document how we're organizing our content.  We also don't consistently organize it.  In the 6 or so years that I have worked at Microsoft, the organization has fundamentally changed a number of times - this certainly does not help..

Anyways, tell me about the challenges that you have faced in learning how to develop using Microsoft products.  I have been working on learning Windows Phone 7 and I have definitely seen the same issues that I heard about in addition to others.  Speaking of, you can download a WP7 powered blog reader for the See Also blog, grab it in the Zune marketplace here: See Also Blog Windows Phone 7 App.

See Also