The Redmond Reality Distortion Field (RDF) and Developer Documentation

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.

Comments

• Anonymous
  January 04, 2011
  Sorry to point this out, but you used the term "resonated" in an article about the Redmond RDF. I've heard several Microsoft employees mention that's on their banned word list, the comedy was amplified when I got to the section about Terminology Common to Microsoft. I hear resonate occasionally used the way softies do, but coming from official and unofficial channels Microsoft uses it about 50 to 1 with the real world, in my personal experiences. Thanks for taking the time to reflect and look at ways to better relate to the developer community as a whole, well written piece.

• Anonymous
  January 04, 2011
  The comment has been removed

• Anonymous
  January 04, 2011
  Resonation is required for the distortion field... duh.

• Anonymous
  January 04, 2011
  The comment has been removed

• Anonymous
  January 04, 2011
  I wonder if RDF is the cause for requiring Windows Vista/7 to develop Windows Phone applications. I know Windows XP isn't supported because of the emulator. But is it because it does not support DirectX 11? If it is, is it really necessary to have a Dx11 based emulator? Is the emulator enough to dismiss XP developers completely? Or was the RDF field who made MS Employees beleive that every windows developer had access to Windows 7/Vista machine (most of the time anyway)?

• Anonymous
  January 04, 2011
  "Customers understand the terminology common to Microsoft". I can't believe an MS employee can write that phrase without spontaneously combusting. After over 20 years of developing using Microsoft products, and being a founding MSDN member, my primary pain point with MS development facilities has been vocabulary. MS consistently invents terminology for their products, and then fails to define the terms or explain them adequately. The worst offender, of course, would be COM development. Even though I have maintained a heavily COM-based application since 1999, I still can't define "apartment threading" or "moniker".

• Anonymous
  January 04, 2011
  I've said it before, I'll say it again. COMPLETE code samples. I can't tell you how many times I've opened up a code sample to find that it is using an object that can only be instanced through a parent object with no mention of the parent object. You can link both the parent entry and the child entry to the same code sample. In short, the code samples should compile. I should be able to copy and paste it into the IDE and WATCH it work.  

• Anonymous
  January 04, 2011
  The comment has been removed

• Anonymous
  January 04, 2011
  This is a Non-problem.  Just use OSX and forget MS.

• Anonymous
  January 04, 2011
  You really think there is not a Cupertino RDF?   I mean the address of 1 Infinite Loop should tell you all you need to know.

• Anonymous
  January 04, 2011
  I'm currently working my way through some Self-paced Training Kits.  I've found that the instructions for the coding exercises is incomplete, inaccurate, or doesn't explain alternatives.  For example, an exercise that requires SQL Server and assumes SQL Server Express is available.  Some organizations do not allow SQL Server Express.  An explanation of how to set up an SQL Server database would have been helpful.  I'm sure MS has a quality review team for Microsoft Press, but maybe it should be made up of people that don't know squat.  

• Anonymous
  January 04, 2011
  The problem that you describe is not specific to Microsoft. It is rife throughout software development environments, from small to large, wherever software is being developed for internal or external customers who are not the developers themselves. I make the mistake myself, even after more than 42 years of developing software. I think it would be useful to compile the symptoms of reality distortion fields, summarize them in a single document, and get senior developers and development managers to read it. Then we might be able to avoid such mistakes as "ribbons" and other such transgressions.

• Anonymous
  January 04, 2011
  Regarding documentation and APIs, a main issue is that the quality of the documentation has dropped a lot (e.g., there is hardly any information about the cause of each function return code. or the range of allowed input data, missing samples, annoying machine-translation by default, URLs get defunct) and the amount of technologies has multiplied (e.g. GDI, GDI+, DirectDraw, Direct3D, WPF, Direct2D) without overall improvements - e.g, when doing graphic programming I end up using plain old GDI for a bunch of tasks like text output since newer APIs did not provide the same result. Thus, please concentrate on evolution rather than trying to reinvent the wheel all over the time. The Tablet PC was a good idea and way superior than todays popular low-end pads, but targetting a conservtive business market rather than an innovative student/art/home market was a bad idea. Doing it with underpowered low-res devices made it even worse.

• Anonymous
  January 05, 2011
  @Paul - Thanks for all your thoughts! re: "software documentation across the board is so poor is because Microsoft sets a very low standard" It's very interesting that you say this because we actually make a conscious effort to standardize the quality and completeness of our documentation.  I'm going to see if I can get approval (both legal and political) to blog about this but Microsoft /does/ have a commitment to the best quality in developer documentation and I am working on finding ways to identify topics where there is poorly documented content using analytics.   Also, don't forget to click the "Send comments about this topic to Microsoft" link when you see glaring omissions as you've described.  I talked briefly about this before in "So You found a documentation Bug" - blogs.msdn.com/.../so-you-found-an-sdk-documentation-bug.aspx but the short answer is that sending email to that link will get feedback to authors. @Chris re: "COMPLETE code samples" Feedback received!  I'll try and escalate this to managers on the programmer documentation team. We have been trying to address this need with samples like Hilo: http://code.msdn.com/hilo and we are making a conscious effort to improve samples in the future.  I like that you call out the need to have debuggable source code though, that level of specificity is really helpful. @Mike Cupertino is home of the master of all RDF, Steve Jobs! @Gus There should definitely be an internal memo about our myopia.  I believe that product planning delivers many such memos but I have no idea how many people read them fully. @TS Yes, there is definitely API/SDK gloat both in shipping products as well as on MSDN.  This creates a larger challenge that we have tried to address with developer centers.  However, the reality remains that most people discover our content through search, which has a tendency to promote older (e.g. dusty and broken) content when people search for things like "windows graphics programming".

• Anonymous
  January 05, 2011
  I could really relate to your recent post (dare I say that "It resonated with me"?).  I find the Microsoft technical documentation inscrutable, mostly you have to learn by finding an example and trying to adapt it, hoping that there isn't some obscure difference between your situation and the author's that will prevent the example from compiling or running, or producing the required results.  When it doesn't, you poke around changing things until it does, with little or no understanding of what you are changing.  The result: fragile systems that work because they have been tested to exhaustion (of the developer), not because they are engineered so that they don't fail.  I recently wasted two weeks trying to get video working with avicap in a Windows Forms application, when I should have been using direct show.  As far as I know, there is absolutely NO documentation that tells you what your strategy for managing video should be in a Windows program, a web program, etc.    

• Anonymous
  January 05, 2011
  The comment has been removed

• Anonymous
  January 05, 2011
  The comment has been removed

• Anonymous
  January 05, 2011
  @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

• Anonymous
  January 05, 2011
  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.

• Anonymous
  January 08, 2011
  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.

• Anonymous
  January 31, 2011
  @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.