Windows Confidential: Feature-colored glasses
If you can’t explain your feature without using buzzwords, then don’t expect anybody to understand you.
Raymond Chen
One of the things you have to remember when writing documentation for external consumption is that the person is reading your documentation because they don’t know everything you know. When you’re trying to explain your feature to somebody, you need to stop and take off your feature-colored glasses.
After all these years, I still had no clue what Windows CardSpace was. In a discussion about Windows Live ID (as it was then known), somebody answered a question by quoting from a section of a Web page titled “How Does Windows Live ID Participate in the Identity Metasystem and Work with InfoCard”:
“Microsoft is working with others in the industry to create an identity metasystem that brings existing and future identity providers into a connected identity ecosystem and empowers end users to control the use of their identities. The Windows Live ID service will participate in the identity metasystem as one identity provider among many, able to accept claims from other identity providers and transform them so they can be used within Microsoft online services.”
Here’s what that paragraph sounded like to me:
“Microsoft is working with others in the industry to create a buzzword that brings existing and future buzzwords into a buzzword and buzzwords users to buzzword. The Windows Live ID service will participate in the buzzword as one buzzword among many, able to buzzword and buzzword them so they can buzzword.”
At that point, I stopped reading and asked if anybody was able to translate that paragraph into English. Nobody could, but a few people privately told me, “I thought the same thing, but was too afraid to say anything.”
All of my attempts to learn about CardSpace led nowhere. The people who wrote the CardSpace documentation assumed that the consumer was already familiar with CardSpace. They cheerfully explained that CardSpace managed cards, which was the unit of claims-based identity. In other words: “CardSpace manages buzzwords, which are the unit of buzzword buzzword.” I gave up reading the documentation at that point.
Here’s another example of one of my failed attempts to figure out the elusive nature of CardSpace:
A demo conducted by the CardSpace project manager began with a section on “What the end user will experience.” That was great, because I could see what it meant to me—the guy who had no idea what CardSpace is supposed to be or how it operates.
That demo consisted of a Web page that said, “Click the button below to submit a card.”
OK—the demo had already lost me from its very first screenshot.
“What is a card?” I wondered. “Is this asking me for my credit card?”
I powered through anyway. The demo clicked the button, and a new dialog box popped up. “Here, you can see that I have a selection of cards available.”
It still hadn’t told me what a card was. Where do cards come from? Why are they useful? Do they come from the CardSpace card fairy?
I stuck with the demo nonetheless. The demonstration selected a card, and then showed a bunch of XML on the screen.
That was the UX? I clicked a button I didn’t understand and was shown a dialog filled with magic beans. Then I selected one of the magic beans, and some XML showed up on the screen?
I went to the online help for CardSpace. I figured, “This is the documentation specifically written for non-technical users. Surely this will explain to me the whole point of this CardSpace thing.”
Well, at least that documentation was a tiny bit better. The online help told me that CardSpace is “a system for creating relationships with Web sites and services.”
That didn’t sound like anything I wanted. I didn’t want a relationship with a Web site. I just wanted to visit CNN and read the day’s top stories.
At that point, I gave up entirely. I realized that it’s one thing if your upper management can’t explain your project. It’s another thing entirely when you yourself can’t explain the nature of your own project.
To be fair, the CardSpace team was set up by their environment. The product was designed for and lived in the world of digital identity. A common property of the digital identity world is that nobody there is able to describe what they do without resorting to buzzwords. The longer you spend time in a world where everybody talks a certain way, the more you assume that everybody talks that way—even if it’s only the people in your little clique who talk that way.
You must have the self-awareness to realize that you’re making this mistake, and put yourself in the shoes of somebody who has not spent the last several years speaking your field’s peculiar jargon. Only when you bridge the gap between insiders and outsiders can you say that you’ve succeeded in communicating.
.jpg "Raymond Chen")
Raymond Chen’s Web site, The Old New Thing, and identically titled book (Addison-Wesley, 2007) deal with Windows history, Win32 programming and security risks posed by annoying MIDI files.