See Also:

Gus Class's Windows Developer Education Blog

The Redmond Reality Distortion Field (RDF) and Developer Documentation

The Redmond Reality Distortion Field (RDF) and Developer Documentation

Rate This
  • Comments 21

I just saw a couple of fun posts about the Redmond Reality Distortion Field (RDF) and it really resonated with how we organize our developer documentation and how we think about our products.  The gist of what the RDF means in the context of Microsoft is that we oftentimes have an unrealistic perception of who are customers are and how they think about products.  A great example is the Tablet PC, Microsoft set the unrealistic expectation in 2000 that customers wanted a pen-powered device (that was underpowered in exchange for long battery life) and that it would need to be running a full-featured OS, oh, and that customers were willing to pay more than they paid for a normal laptop.

At any rate, the following examples and comments are some of the Redmond RDF issues that I can think of:

Customers will be able to find everything because it's organized in the Developer center.

When I started working at Microsoft in 2005, I had some experience programming for Windows.  When I was in school, I was taught C++ and my professors frequently provided libraries and utility classes along with resources for learning.  I never, throughout all of college, was directed to a developer center for learning content.  In research projects, I never discovered a developer center.  Setting the expectation that customers will naturally flock to a developer center is unrealistic and we later changed the way that content was created to assume that customers have reached it without going through a developer center.

Customers know which products / features to use based on their needs.

Take a look at the multimedia learning path for Windows development.  This tries to disambiguate the differences between:

  • Code Objects
  • Core Audio
  • Media Foundation
  • DirectShow
  • Windows Media SDK
  • Windows Media Audio and Video Codec DSPs 

All which are various tools that can be used to program multimedia applications in Windows.  If you are a customer who needs to play back an audio file in your application, where do you start? If you work at Microsoft, you probably use the feature that is closest to the particular feature you are working on: e.g. if you are creating a Zune and it's supposed to play nice with Xbox, you would use whatever multimedia SDK the Xbox used.  If you are programming a  Windows  app and it's supposed to have multimedia support integrated with Shell features, a Microsoft developer would most likely opt for whatever ships in the box with Windows.  However, if you are someone from outside Redmond, there are too many options, and there are rarely code precedents that have been set in a particular customer's code.  This is even worse if you are a hobbyist developer.  

To address this, I have considered creating a technology page that differentiates between Legacy (supported but going away) technologies, Stable (newish but old enough that it's not bleeding edge), and Next Generation (the technology that Microsoft is most likely to be moving forward with).  However, this is a very tricky situation to be in because in many ways, we don't know which technology is going to make it into future versions of products and for strategic reasons we sometimes can't tell customers.  Additionally, there are political fires that could be started if a particular individual's / team's product doesn't make the "Future" bucket or ends up in the "Legacy" bucket - signalling or potentially influencing the fate of an SDK or product.  I really don't know how best to handle this challenge, but I am definitely  aware of our myopia here.

I feel that this example is one of the most dramatic cases where we have trouble understanding the customer's needs and can make it easier for customers to do what they need to do with our technology.  Please let me know if you have any suggestions for ways I can help this.

Customers will Read the Fun Manual (RTFM)

While trolling in the MSDN forums for coding for Windows, I oftentimes encounter a developer support case where a moderator assumes a customer asking a question is familiar with a technology because they read the documentation.  The reality is, not all of our customers are "reading" learners.  Some people learn by doing or learn by watching. Our content is very heavily weighted to "library" content: reference documentation, architecture overviews, programming guides, and glossaries - all great for some types of learners (these guys hanged out in the library in College ^_^) but that are really bad for other types of learners.

I'm currently working on getting more video content produced and featured in the developer center.  I'm also working on producing content that is well suited to podcasts for those learners who prefer to learn by listening.

Related to this is the assumption that....

Customers Understand the Terminology Common to Microsoft

I wrote a post about Microsoft's terminology / nomenclature earlier last year that tries to illustrate how our internal thinking and terms are distorted.  To see how this can effect things, take a quick look to our friend Google.  Searches with the term developer and every imaginable iteration of it are much more likely to return results on MSDN than searches with the term program or code.  Our content is very much focused to our own terms and I have been working on loosening up the terms that we use in certain contexts to try and make our content more discoverable.  Additionally, the learning paths try to prime customers to the terminology frequently used in the particular context of a technical domain and I will be working to improve / augment those learning paths with new content that helps to disambiguate the common terms.  

Let me know if you have any other examples of the RDF in our documentation / content or have ideas about how we can help with the issues I am aware of.

Leave a Comment
  • Please add 8 and 1 and type the answer here:
  • Post
  • How about actually including documentation with the product?  MS Visual Studio 2010, for example.  I think it's fantastic that the documentation is available on-line, but consider it atrocious that it's ONLY available on-line.

    If I need reference information for a given topic, and I don't have an available Internet connection, I'm stuck.  Whose brilliant idea was THAT?  Note to the documentation team: while the internet connection at Microsoft is always on, the same cannot be said of other locations...

  • MS, You said, "...atrocious that it's ONLY available on-line"

    that is an incorrect statement, as you can opt for either online or local help.

  • @MS

    As @Glickerman pointed out, the documentation /is/ available offline; however, the way of getting to it has changed slightly and also the documentation for Windows programming is encapsulated in the Windows SDK rather than in Visual Studio (probably another RDF topic itself!).  

    Visual Studio is not the same as Windows Programming.  The related hooks into Windows programming ship with the Windows SDK and documentation related to the Windows SDK is / can be installed in the Windows SDK.  However, with the release of 7.1 the docs were removed from the SDK to reduce the size of it. The offline documentation can still be installed and I wrote a blog post about this earlier:

    Where Did the Offline Docs Go in Windows SDK 7.1? blogs.msdn.com/.../where-did-the-offline-docs-go-in-windows-sdk-7-1.aspx

  • Microsoft has had a long history of renaming the old to make it appear new, thus completely confusing everyone who lives outside their RDF. Also MS seems to think everyone has nothing better to do than keep up with all things Microsoft. Neither of which help you.

  • The worst example is the documentation that comes with Visual Studio 2010. Incredibly, there is no index, no usable table of contents, and no usable searching. These were all available in VS6 and VS2005.

  • @gclassy,

    Thank you for the insightful post. Microsoft isn't perfect (as we all know), but I am glad to see that they are listening to end-user input with an eye towards making documentation easier to use. Don't get discouraged by the trolls - I have seen steady improvement over the last few years.

    Thanks.

Page 2 of 2 (21 items) 12