Sunless In Seattle

They probably won't invite me over to Redmond again. After telling me for weeks about the wonderful summer weather there, it rained for most of the two weeks I was on site. Not many people would suggest that I have a magnetic personality, but it sure looks like the English weather followed me across the pond. We even had hail one day (in the middle of August), followed by a small tornado. And I'd taken shorts and sun cream with me. But I suppose after it rained almost the whole time during my last two trips, I should expect it. Maybe I can earn a few dollars extra by selling people my travel plans so they can plan their holidays around my trips to Redmond.

Mind you, Washington State is one of the most beautiful places I've ever been to, and it wouldn't be lush and green without the rain. And, by some extreme good fortune, the two days when the sun did shine I was treated to a boat trip round Lake Union and Lake Washington (we waved to Bill, but he didn't invite us in for tea); and a trip to see Snoqualmie Falls (absolutely amazing!) and the Northwest Railway Museum (they obviously read my blog where I confessed to being a railway enthusiast). Though I had to laugh when a colleague said how she'd told her friend that I was a train spotter, and her friend was horrified - "What?", she said, "You mean like in that awful film...?"

So the nice-weatherness was a great deal less than I expected, yet the breathtakingness of the falls was substantially more than expected. But that's how life works. Sometimes you get more than you expect, and just as often you get less. In fact, only last week my wife told me about how one of the girls who works in her office was complaining after going to see "Mamma Mia" that the film was full of Abba songs. She doesn't like Abba...

Here in the little office in England where I engineer documentation for p&p, expectation is something that constantly raises its ugly head. What do people actually want or need in terms of guidance when they install a product such as Enterprise Library or read the Web Services Security Guide? As you'd expect, we go to considerable lengths to collect feedback from focus groups consisting of specialists, customers, and industry leaders; from satisfaction surveys; as well as through in-house reviews and direct feedback from documentation links and CodePlex forums. And, in general, the results are encouraging. In the past, in some software companies, it seems to have been the case that the code was king and the documentation an afterthought. But, generally that's changed as companies realize that users expect more. And, let's face it, as the sole purpose of my job is to create guidance rather than code, what people expect has got to be a major focus.

But what exactly do customers expect from documentation and guidance? While there is never going to be a single answer, getting it right should give the maximum help to the most people. One of the things we are working to achieve is to provide a range of documentation on architectural and pattern-based topics that suits the wide range of consumers. That means everything from introductory "Getting Started" topics to reference documentation such as API references, key scenarios, and checklists.

And, of course, there are different formats. Videos are a great way to introduce technologies and practices, and to show development stages and techniques. But they can be limited in reach due to bandwidth limitations and the time commitments required both to create them and to watch them. Slide decks are also useful, but without a commentary like you'd get at a conference presentation, it's often hard to get real depth with just bullet points and schematics. Ideally, you would sit down with an expert in the technology who could explain it all to you and answer your questions. Microsoft do just this through summits, conferences, and their evangelism groups, but unfortunately we don't have enough staff in p&p to provide every developer with their own personal trainer.

In the end, the major source of information has to be the written word; as a help file, Web pages, a white paper, a PDF, or a printed book. We need to explain scope, concepts, objectives, scenarios, and details. The guidance should work for relative beginners, skilled developers, technology experts, and software architects. And for each group it must be set at a suitable technical level, and written using the appropriate terminology. It also needs to be localizable into a number of different languages.

And here we run into one of the major issues we're trying hard to tackle. Microsoft publishes a style guide for documentation (it's the bane of my life sometimes) that specifies in excruciating detail exactly which words you can use, how to phrase them, and how to construct the required grammatical content. This helps to avoid confusion, provides standardization across products, gives a common appearance that developers recognize, suits different cultures, and works with automatic translation tools. So the tone and style of the documentation is pretty strictly controlled.

However, at the same time, there's an increasing feeling that our documentation should be more "approachable", "personable", and "entertaining" - and even, shock, horror, "exciting". I'm not sure exactly how exciting you can make a table describing the methods that resolve objects in Unity - maybe throw in a few bad puns like "...the object of this method..." or " should resolve to use this method when...". As to exciting, how about "When you click this button, something will happen ... perhaps ... why not try it and see...?".

But, seriously, how do you decide where to pitch the level of the content? Would something lively with a few jokes thrown in make learning easier? How much would this style grate after a while? Should we use the "we apostrophe" approach instead of the "you formal" style (for example, "Now we'll add a handler to validate input data" rather than "Now you will add a handler that validates input data")? And would jokes made up by some semi-deranged Englishman (me) seem funny to people in other countries? I told the joke about the golfers to a colleague before I published last week's INAG article and he had no idea what I was talking about - I had to explain it to him. And he was from the US. So much for us sharing a common culture.

Maybe, instead, we should just continue to publish a range of guidance aimed at different levels of developer/architect and at different levels of product complexity. For example, "Getting Started" guides that compare features to common household objects and situations (like the "Getting Started" articles linked from the p&p Home page) as well as high-level bullet-point technical feature reviews for architects to use when planning major projects. And, alongside, reference-style documentation like that we produce now for Enterprise Library and similar products. Let me know what you want to see - I'm open to suggestions...

Meanwhile, by some strange coincidence, I had previously been ruminating about guidance phrasing while sitting in the departure lounge at Amsterdam airport for several hours on my way out to Redmond. You know what it's like. After a couple of hours you have read all the warning and information signs, counted the ceiling tiles (twice, just in case you got the total wrong the first time), given up trying to decipher the language the two people behind you are speaking, and started reading your food. In my case, the food was a bag of potato crisps/chips made by a company I'd never heard of before: Sirhowey Valley Foods of Gwent in Wales.

Now these guys make serious crisps and chips, and are proud to say so. The front of their packets talks about how they make their chips using real onions and mature Cheddar cheese, and how they definitely would never cut corners. Then, on the back, the packet has the usual "If you are not completely satisfied..." bit. Except theirs says:

"Although all our chips are made with the finest natural ingredients, some may contain traces of corners. If in the unlikely event a packet does contain any corners, please do not hesitate to send the packet and contents back to us. Don't forget to enclose the offending corners. We would also be interested to see any spare photos from your holiday, if you have some." (see

Maybe this is the way forward. We can describe how hard our people work creating the code and documentation. The endless hours and countless pizzas, and how they only pause to wipe the rivers of sweat from their keyboards. And how they ruthlessly test almost to destruction the code and documentation, until it begs for mercy and crawls exhausted into the MSI.

Then on the last page of the documentation we would add our "If you are not completely satisfied..." message:

"Although our documentation undergoes rigorous editing and testing, some may contain traces of bad jokes, pointless puns, and unsuccessful attempts at humor. If, in the unlikely event a guidance item does contain a combination of such words, please do not hesitate to translate it into a different language and see if it is still funny. We cannot be held liable for damage caused by spilled coffee or rapidly expelled particles of pizza. Also note that persons of nervous disposition should avoid reading any sections of the documentation denoted by a "This part may be exciting" warning label."

And please don't send your spare holiday photos to us....

Comments (1)
  1. Dave Sussman says:

    Next time she goes shopping, ask Tina to buy you a carton of an innocent smoothie. Read it all, even the bottom.

Comments are closed.

Skip to main content