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 2 and 5 and type the answer here:
  • Post
  • 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.

  • There are lots of colloquialisms that I am unconscious about that I use in regular discussion and far more that slither around internally at MSFT. I will take another review at our standards for banned words because I probably have missed more than just this one; however, there are some questionable words in our banned lists (voodoo, vernaculars, pimpin' to name a few).  

    Still, there are tons of overloaded words that I can think of that I always notice people misusing internally (actionable is my latest pet peeve) and an editor on our team takes it to another level with a regular newsletter summarizing terms commonly misused.

    Thanks for your comment and commentary on my word choice, I have never heard "resonated" was banned - I'm writing my editor!

  • Resonation is required for the distortion field... duh.

  • I have been a software engineer and keen observer of technology companies for over 30 years, and I was fascinated to read about the Redmond Reality Distortion Field. I am sure that this is just the tip of the iceberg when it comes to explaining why so many Microsoft products are badly positioned and lacklustre. The tablet PC was a perfect example of Microsoft having a great basic idea (as proven by the success of the iPad) and then driving it into the rough. The answer is very simple, and is understood by even very small businesses: use market research. Don't develop something just because it seems like a good idea - develop it because you have proved that it is what people want. Ignore what you think you know about the market - you are techno-geeks, like me. Follow the market research.

    The other aspect of this, which you touched on, is internal politics. Internal politics seems to be responsible for so many bad decisions in Microsoft. The answer is that culture - core values - comes from the top. If the people at the top behave in self-serving, devious ways, that culture will permeate the organisation. If the people at the top clearly believe in openness, honesty, being passionate about the customer and being fair and supportive to their staff, that will become the culture of the whole organisation. What are the core values at Redmond?

    As for developer documentation. I have been a Windows and .NET developer for 15 years, and I can say that the reason that software documentation across the board is so poor is because Microsoft sets a very low standard. So much of the documentation is of the form "DataSource property: set this to the data source". Some is far worse - try looking for help on the speech engine. What is desperately needed is an explanation of each feature - why is it there, what does it do, when should you use it. And then real-world examples linked to real-world scenarios, not scenarios that are so simple that they have no relevance. Microsoft is spending huge amounts of money developing great software, but it then fails to explain to anyone what it's for and how to use it. When I come up against a problem and search for the answer on-line and in MSDN, I generally find many other people with the same problem. I am much more likely to find a solution in some random posting than in MSDN. Worse still, the postings are very often misguided or have overly complex solutions - again, because the information simply isn't available from Microsoft. Come on, guys - what's the point of spending so much money on developing software if you don't then take the trouble to explain what it's for and how to use it.

  • 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)?

  • "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".

  • 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.  

  • Make sure error messages generated by your products help diagnose the problem!  My favorite pops up if I make a field-level error when updating a database table.  The error message is:  "Errors occurred."  Gee, thanks!  And, when using the old ADODB library, table updates are often impossible:  "Query-based update failed to find the record" (or whatever that message is -- I think you know what I'm talking about.), even if there's only one record in the recordset and that record includes the primary key.  That one has led me to conclude that the whole ADODB library is basically worthless.  The only reliable way around that error I've found is to build an update query from scratch inside my code, and then call the database object's Execute() method.

    Someday we'll migrate to .Net, but it will be years before we're out from under ADODB.

  • This is a Non-problem.  Just use OSX and forget MS.

  • 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.

  • 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.  

  • 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.

  • 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.

  • @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".

  • 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.    

Page 1 of 2 (21 items) 12