Random Disconnected Diatribes of a p&p Documentation Engineer
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 "...you 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 http://www.realcrisps.com/REAL-(Potato-Chips)/REAL-Words.html)
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....
At last I can document something that might, possibly, be of marginal use to those one or two readers who mistakenly stray into the quagmire of my unrelated weekly ramblings. For the last few months I've been fulfilling my new role as an out-of-sight-and-out-of-mind remote documentation engineer (that's a documentation engineer who's remote, not an engineer who writes remote documentation - though, having read some of my scribblings, you might dispute that assertion). Anyway, recently I was beamed up to the mother-ship to spend a couple of weeks onsite at Redmond. I suspect they just wanted to see if the weird English guy they accidently offered a job to actually does exist.
So a while ago, while preparing my shiny and tiny XPS laptop for the trip, I had a minor moan about Vista's backup facility. But little did I realize that worse was coming my way. My laptop usually lives on the corporate domain, even though I only connect to the domain over a VPN and am not connected during login to the machine. The cached domain credentials allow me to log into the machine without being connected, and then the O/S authenticates me on the domain when I connect to the network.
All fine so far. Except that, for some reason, one day it suddenly stopped me from logging in to the machine. I assumed that this was because I hadn't physically connected to the domain for several weeks. So it should all sort itself out when I can reduce the 5,000 mile gap between my laptop and the nearest corporate Ethernet socket. The domain controller would be forced to accept that I'm not just some ethereal figment of its Active Directory, and would gleefully welcome home it's long-lost prodigal son.
Now, I'm not generally known to suffer from wild spasms of optimism. And so I wasn't really surprised when the long-awaited fusing of my tiny little Dell with the corporate big-iron simply resulted in an Event Viewer full of error messages, a pop-up telling me there was an error in my profile, and the machine refusing to persist any changes to the environment. Every logon was accompanied by a long wait while Vista "prepared my desktop" (I could have built a whole desk in the time it takes), a task bar full of useless notification icons (what the **** do they all do?), dialogs welcoming me to the exciting world of Windows Vista (yes please, I'd love to watch the introduction video again), the Home page of Dell Support's Web site (just in case something broke while booting up?), and - of course - none of the useful stuff I set up last time.
After a quick consultation with the onsite server admin guy (hi Mike), it seemed like this is not an unknown issue - he had a laptop suffering from just this malady. While he hadn't had time to investigate, he did confirm that it was a problem with Vista not being able to create the profile folder on the local disk. But why? The relevant folder did not exist, the parent folder was not read-only, and a quick test by manually creating the required folder had no effect. So it looked like I was in for another of my regular hunt-round-the-Registry-and-delete-stuff exercises.
Of course, as per accepted administrative guidelines, I need to warn you about editing the Registry. So, before you start, make sure you write out your will, lay in supplies of pizza and cola, and say goodbye to the kids and the dog. You might also like to wear some protective clothing (a T-shirt with a suitably inane slogan will do), and make sure there is nothing valuable in the direction you are likely to throw the unbootable machine afterwards.
Once prepared, locate the Registry Key:HKEY_LOCAL_MACHINE \SOFTWARE \Microsoft \Windows NT \CurrentVersion \ProfileListThis contains a subkey named with a SID for each user account on the machine. In theory, there is one for each of the named folders in the C:\Users folder on your disk. If you select a SID subkey, you'll see the user name in its subkeys, so you can compare each one with the disk folders. You should find ones for the Administrator, Local System, and Network accounts; as well as ones for all the users registered on the machine or in the domains you've joined.
My machine has led a busy existence during its short life, moving between three domains and having a couple of local users. During a "routine clean up", I seem to remember deleting some of the subfolders in the Users folder - though I was, of course, careful not to delete any currently registered users. What I discovered was the Registry still held references to profile folders for accounts that no longer exist on the machine, but not one for the domain account I was trying to use. I have no idea why this caused a problem, but I decided to tidy up the Registry while I was in there and deleted the SID subkeys, including all their child subkeys, for all of the non-existent user accounts.
Then, having decided which wall would be the target for an airborne laptop, I rebooted. And, magically, it all worked. Instant logon to the domain, wireless certificates downloaded and installed, and no errors. Quick reconfigure of the desktop, log off, log on again, and it remembered my settings. No more "Welcome to Vista" stuff; and everything working just as it should. Even Outlook managed to find its Exchange Server without the usual application of a large stick. Amazing. Maybe I can actually get to love Vista after all...
(OK, need a good, hard-hitting, gritty opening sentence this week to get people interested. Here we go...). Last week I went shopping. (Hmmm... not quite the impact I wanted, but press on regardless). I wanted a new battery for my camera, so I popped into a local specialist. "Hi," I said breezily, "I need a battery for an Olympus 1010 Stylus camera". "OK," replied the obviously knowledgeable young man behind the counter, "just fill in this form". He presented me with a long form where I had to enter my name, address, credit card details, and a myriad other details. Finally, when I gave it back to him, he said "Right. We don't actually have one in stock just now, but it should be here in a couple of weeks". Needless to say, I tore up the form and stormed out in disgust.
Across the road, I noticed a rather interesting looking computer store, and decided to have a wander round. After about half an hour, I'd filled my shopping basket with a dozen or so items, and sauntered over to the checkout. Suddenly, a rather aggressive looking lady took my basket off me and disappeared. After a few minutes she returned and gave me back an empty basket, explaining that there was a problem with the cash register, but I was welcome to go round the store again and refill the basket. I decided not to bother.
Somewhat irritated with the day's events, I thought I'd calm my temper with a cup of coffee and half an hour with my newspaper. A few doors down the street I found a nice coffee shop, though I was more than a little perturbed to see a sign on the door that read "Warning: for your safety you should only enter these premises wearing a red satin waistcoat and brown leather shoes". Now, red doesn't go with my complexion, and I don't own any brown shoes, but I decided it was worth the risk. However, I did ask the pleasant young lady behind the counter if I could see the manager to complain about this blatant discrimination. She replied that I had to tell her the password before I could speak to her boss. "How can I find out what the password is?" I asked. "I don't know", she replied, "He always keeps it in a sealed envelope in his pocket".
Deciding that drinking coffee here was perhaps beyond my risk threshold, I left and strolled across to a large branch of a national well-known supermarket chain. There I had a nice cup of coffee in their restaurant, wandered round and collected all the stuff I needed, was greeted by a helpful and efficient checkout operative, and was on my way home in no time.
Of course, you will probably have guessed (if you are brave enough to have stuck with it this far) that the preceding is all a huge fabrication. Or, at least, it's partly a fabrication - and may just serve to indicate how stupid things can get in our modern, high-tech, shop-on-line society. In fact, last week I did...
It does seem strange that, after more than ten years, we still seem to be struggling to provide an Internet that works reliably, works in all browsers for all users, and actually makes life easier. People even seem to spend more time worrying about how that CSS border line is "two pixels off", and that some browsers don't "fully support all the standards". It's not hard to see why the big boys in this game continue to grow, while so many others fall by the wayside. OK, so it is hard to get right, especially for small sites with limited resources. Perhaps the answer does lie "in the cloud" with "Software plus Services" (S+S).
So would you trust some outside organization to provide all the services your business (or hobby Web site) needs? In my previous life as a creator of retail software and purveyor of IT services, I always said that I would provide my own infrastructure and services to make sure it did what I wanted, was always available, was secure, and was under my control. I run my own Exchange Server, public DNS, and Web sites. Yet, looking at my systems, I was surprised to see how much I already outsource. Before becoming a 'Softie, I used Powernet to filter my incoming email. I used LunarPages to host large file downloads and one of my Web sites. I used DigitalRiver to take orders and process payments for my software products. And this blog is hosted on MSDN. One of my colleagues even uses an online source code repository and an online backup facility.
I guess when you think about it, it's hard to see why anyone would start now to create a new general-purpose search engine site to compete with the few guys who already own the market. Why would anyone want to build a new auction site, when it's so easy to use EBay and the like? And small retailers seem to be congregating in their thousands around the in-store shopping services available from Amazon and others. Maybe the future is a relatively small number of "in-cloud" service suppliers, with the majority of sites hosted there.
But why "cloud"? In his blog post "Can We Please Define Cloud Computing?" (which presents some interesting views of the topic) Mark Hopkins mentions that the first time he saw the use of of the cloud symbol was in diagrams of MCI's ATM router mechanism. I remember way back when we were writing our first Internet books (about Internet Explorer 3) at Wrox Press we decided to use a cloud symbol to represent the Internet in our schematics - it seemed the obvious choice and represented stuff that was "going somewhere else, but not sure how". Isn't it amazing how a whole technology can get its name from a PowerPoint shape...
Here in England, architects (the kind who design houses and office blocks) seem to have a pretty poor reputation. Other than the "stars" who win prizes for designing skyscrapers, or weird shopping centers that look like an armadillo that wandered into a chrome-plating factory, they seem to be universally reviled. Perhaps it’s the same in the US. I remember once hearing the quip "Don't tell my mother I'm an architect, she thinks I play piano in a whorehouse". That sounds like a US-ism if you ask me.
We have a TV show named "Grand Designs" where people with huge ideas and equally huge piles of spare cash build strange houses. While all the houses are very different, all the shows have some things in common: it always costs more than they budget, it always takes longer than they planned, and they always fall out with the architect. Somehow you just know that the cantilevered roof won't pass building inspection, the windows won't fit, the kitchen will be totally impractical, and the rain and snow will ruin the exposed timber beams before the roof tiles arrive (though maybe you can't actually blame the architect for that).
The only show I can recall where it all went right was a young couple who bought an old pumping station for about £5 ($10), made a fortune selling the pipes and tanks for scrap, did all the work themselves over a two year period, and turned it into the most fabulous place with a lounge area so big they used a cut-down Mini car as a desk - and you didn't notice it till they pointed it out. Strangely, the house is only a few miles away from me, but when they sold it, the price was the equivalent of a million dollars US. Somewhat out of my reach unfortunately. Shame, I could probably have parked my car in the bathroom to wash it.
So, anyway, I wonder if software architects face the same problem. Do developers stand back from some complex business layer component and mutter "We'll have to chop some lines of code off that if you want it to fit into the server...", or "That data access layer will fall over the first time we get a decent breath of wind blowing off the hills...". Maybe the administrator goes off in a huff mumbling "Typical architect, never specified a long enough piece of HTTP to connect the Web server to the database server...". And the project manager is left to give you the bad news that the event handlers the architect specified are only available from one factory in Sweden, and they are closed for the holidays.
As an aside, it's actually illegal in the UK, according to section 20(1) of the Architects Act of 1997, to use the term "architect" in your job title if you don't have "appropriate" qualifications (see Regulation of Title). Though the Architect's Regulation Board seems a bit more relaxed about it these days. But I did hear that at one time they were trying to enforce this and make software people use something like "Software Designer" instead. What they probably meant was "Jumped up geek who does stuff with computers..."
Of course, in building houses terms, the architect is probably long gone when it all goes wrong, or is protected by something in the vast wad of small print. But I suppose you have to feel sorry for them. I mean, in terms of software projects, I never heard yet of one where the delays, bugs, lack of performance, or cost over-run were blamed on the architect. It always seems to be the developers fault. So guys, here's your answer. Lean back in your chair, suck your teeth and make that "not-my-fault" whistling sound. Then explain to the project manager that it's all the architect's fault. He designed it, you only built it...
And maybe add that you couldn't get the right bits...