Random Disconnected Diatribes of a p&p Documentation Engineer
I've occasionally heard developers talk about a "code smell" - subtle indications that lead to the uneasy feeling all is not well with the source code for some application (as opposed, I guess, to the not unknown opinion that everybody else's code stinks). I wonder if there are similar easy-to-miss signs that some piece of documentation or guidance you've been slaving over for weeks is not quite all it should be? Is there an equivalent "docs smell"?
One of the challenges of working in the patterns & practices team is targeting the guidance I create at a level of technical capability appropriate for users; and gauging the relevant experience and knowledge that the users we do target will already possess. Much of the problem seems to relate to the huge breadth of technologies available and the increasing complexity of techniques that are now becoming common. Our primary aim is to provide guidance for users of Microsoft technologies in real-world scenarios. We don't teach people how to write a Hello World application in Visual Basic, or how to use CSS to style a web page. Instead, we aim to demonstrate how development teams, system administrators, and software architects can get the maximum benefit from applying enterprise-ready software, techniques, and solutions.
We do our best to help professionals build applications and services that fulfil meaningful and useful tasks. However, everyone needs to start somewhere. For example, we can't just assume that every user of Windows Identity Foundation (WIF) is already an expert in building Windows Communication Foundation (WCF) services. It may be that the only time they WIF is when building ASP.NET applications. And, conversely, it may well be that someone highly experienced in building web services with WCF has never seen an ASP.NET GridView control. Or know what Razor is.
Of course, Razor is a relatively simple technology to learn. In fact, I've been working on a guidance project for another group (not p&p) that covers it in some depth. And, as we assume that it's a technology primary aimed at newcomers to web development (which may or may not actually be the case in real life), we explain a lot of the theory behind the HTML techniques we demonstrate, and other related web development and data management topics as well. Except we use only C#, including generics and many of the latest fancy syntax shortcuts, without explaining these. OK, so we can't cover everything in one go, and have to make some assumptions on the existing knowledge of the reader. Yet (sniff, sniff) many developers I know who are just starting out with web development use Visual Basic...
A particular topic where this difficulty in accurately targeting guidance is relevant is one of the p&p projects I'm currently working on. We've already produced several related guides on Windows Azure, Moving to the Cloud, Windows Phone 7, and the use of Claims for Identity and Authentication scenarios. Many of the techniques used in the guides and the sample applications are common across these areas of development. However, they are not generally well-known topics, and include a plethora of new terms and technical jargon. The result is that some potential users of our guidance may have difficulty finding the relevant content; especially if they are not already familiar with the technology space.
So how do you counter this issue? We've got some ideas that will improve the visibility of different parts of the content and provide a more definitive road map that will help potential users find the relevant parts. One is to provide a FAQ-style list of topic areas and subtopics that narrow the view into the appropriate areas of the content. Another is to create introductory guidance that steers users into the required area by helping them to understand the different parts of the content when starting from a lower level of prior knowledge.
This doesn't, however, solve the problem of "findability". Even when we apply fancy SEO techniques to the online content, it is unlikely to appear at the top of a search engine results page. These use all kinds of rules, including preference for the most recent content, the presence of keyword repetition, and matching phrases within the topic headings; all of which tend to reduce the prominence of guidance that is created in a form primarily suited to printing as a book. This means blog/forum posts and articles that have just been published are more likely to appear before any of our online content. The result is that the poor users, searching for help on a topic with which they are not already familiar, will find short snippets of information that is often not helpful when starting out with a new technology (or which, in some cases, is just plain wrong).
A typical example of the findabiity problem I encountered was when researching the different patterns for authenticating a service call using a combination of Active Directory Federation Services (ADFS), Windows Azure AppFabric Access Control Service (ACS), and – of course - WIF. So far I've identified around a dozen different architectural scenarios and service request patterns for this, several of which seem to be almost impossible to implement or to actually make work. Or describe in a meaningful way to newcomers. Even helpful blog and forum posts such as "WIF supports SAML tokens but not the SAML protocol" may not be terribly useful to these users as they struggle to understand the technologies. OK, so I can provide overviews, definitions, diagrams, and all the usual guidance stuff for those that stand half a chance of being implementable. Though I'm surprised that Visio didn't pop up an error dialog to say it had run out of arrows while I was trying to sketch out all the schematics.
And when I finally came to write the questions and answers bit for the end of the chapter, I realized that I was OK asking the questions but then I couldn't decide which of the multiple-choice answers was correct. Depending on which blog posts I read, how I tilted my head, and whether I closed one eye, all the answers seemed - at least to some extent - to be correct. Maybe this is actually a good example of a "docs smell", though I suppose I can't really really blame Windows Identity Foundation for that.
But it sure is a handy technology for creating pun-filled blog post titles...
I suppose most people remember which way to change their clocks for Daylight Saving Time (DST) by recalling the phrase "Spring Forward, Fall Back". Even though, here in England, it would be "...Autumn Back", which doesn't work quite so well. And, just to be awkward, we call it "British Summer Time" instead. But here's the rub: why do we do have to keep fiddling about with it?
Years ago we were told that it was to help safeguard our children walking to school on dark mornings. Using GMT in winter means that the mornings are less dark; and going forward an hour in summer means that evenings stay lighter later. However, taking as evidence the fact that there is twice the volume of traffic on the road when the kids are at school than there is in the school holidays, kids don't actually walk to school any more. They all go in huge 4x4s and 7-seat people carriers.
Of course, Governments like to fiddle about with DST just to show they are doing something (I reckon it's a sign of how little meaningful and useful stuff they actually can achieve). So in the past we've experimented with double summer time and with no summer time. And, it seems, everyone complained so much that we always went back to the current system. Meanwhile some countries (such as Russia) are reported to be contemplating abandoning DST altogether, Israel can't decide when it starts and finishes, and there are people here in the UK and Ireland suggesting we have multiple time zones to cope with the fact that there is a half-hour difference in sunrise and sunset times between Skegness on the east coast and Shannon on the west coast.
But what's the real issue now is that here in the UK we are being threatened by a new outbreak of the wonderfully named "Single Double Summer Time" (SDST). No I'm not making it up, do a web search if you don't believe me. Supposedly it will reduce accidents, save lives, increase tourism, bring us into line with Europe, reduce energy bills, increase leisure time, and (quoting from the official literature) benefit "those who attend an educational or training institution". So it's a wonder that the whole world doesn't already do it.
Of course, there are those who aren't happy about it. They say that people in the North of Scotland will be eating their lunch in the dark all though Summer and won't see the sun at all in winter, though I'm not sure how that works. And that there will be hundreds of school children killed in road accidents in the dark, even though they are traveling in a three ton steel box. And farmers will have to plough their fields in the dark, so the furrows won't be straight and people will laugh at them. Or just that it's obviously a scheme dreamed up by the shadowy elite that run the People's Republic of Europe, and so we should naturally complain about it.
However, there is a single far more important factor to consider in this debate. If we do change to SDST, I'll have to stay at work even later in the evenings while I wait for my Redmond-based colleagues to finish their cornflakes and start our daily series of online meetings and conference calls…
I don't know if the term "spend a penny" has the same meaning to people outside our little corner of the world as it does here in England - but if you happen to use email it soon might. Mainly because, according to a report in the newspaper today, there are people in and around Government seriously considering charging a penny in tax for every email you send and receive.
I suspect there are many people who, on reading about this, will be mentally (and perhaps audibly) forming some syntactic expression that corresponds to both the action described by the aforementioned phrase, and the way they feel about the proposal (although I can't actually crystalize that expression into the written word here due to the MSDN Blogs site policy on disseminating profanities).
Of course, if they used the money to transform our creaking telecoms infrastructure into a proper high-speed data network, or even to halt the onslaught of spam and viruses, I suppose you could argue that it's a good idea. But that's a bit like expecting them to spend the vast amounts of money raised from vehicle and fuel taxes on improving the road network. In other words, unlikely. They'll need the money to employ a team of several thousand Email Analysis and Fee Enforcement Officers, a huge palatial office block, and a massive computer system that never actually works.
Meanwhile, in another example of blatant profiteering, I was amazed this week to discover that you now have to pay to drop somebody off at our local provincial airport. East Midlands Airport used to be such a nice small and friendly place, but now they've obviously decided they need to pretend to be a major transport hub. Maybe they're hoping to be christened London's fifth airport (even though London is more than 150 miles away). And it's not even that they are an international airport, or actually fly anywhere useful. Yet they charge a pound just to slow down by the Departures door to toss your passenger (who is, coincidently, their customer) out of the car.
So I suppose, in light of the fact that it's obviously now acceptable to charge people for things while providing them with no tangible benefit, we in the IT world should be looking at introducing the new BlaPro (blatant profiteering) features into our industry. For example, how about charging a "per source code line" fee for users to run your applications? This would have the useful side-effect of dissuading developers from using all those fancy shorthand statements that make code harder to read. And perhaps even make them put their curly brackets on separate lines so it looks neater when people like me come to document it.
Or how about charging a fee for exceptions? After all, it's time consuming writing all that error-handling code. You could pop up a dialog that, along with the perennially useless "Contact your system administrator" message, includes the requisite boxes for the user to enter their credit card details to enable the "OK" button. Surely nobody would complain about an occasional divide by zero error or null pointer exception. Mind you, when management start to encourage developers to generate increased income from their applications this feature may end up having an adverse effect on program stability.
Of course, the operating system manufacturers would also need to consider how they can take advantage of BlaPro as well. I'm all for charging a rental fee for desktop real estate usage. And double if the application decides to stuff things into the notification area or my right-click menus. That might stop manufacturers from dropping shortcut icons all over my desktop every time they fix some security hole in their applications (yes, Adobe Reader, I mean you). Or at least make them think twice about adding shortcuts to every menu, taskbar, and other corner of the OS when I install a program.
Meanwhile, system administrators and infrastructure providers would not be denied their own BlaPro opportunities. OK, so they already charge plenty for renting out rack space and servers, and for the individual transactions performed. But what about DNS lookups? As far as I know, nobody is charging for these yet. Surely there's a whole new market and profit opportunity there.
And, closer to home in my case, it's surely time that documentation started to earn its keep by applying some BlaPro capabilities. We could start to charge for help files and user guides by the sentence - or even by the word. With a special additional charge for words containing more than four syllables. And a special supplemental fee, based on the total number of pixels and the color depth, for schematics and screenshots.
All of which means that, if you managed to struggle this far, you now owe me $8.43. You can email me your payment - remembering, of course, to include an extra penny to cover the email tax...
So when somebody comes to read your gas meter, do you give them a front door key and tell them to pop in any time they like? Or when you hand over your credit card at the supermarket checkout, do you let them know it's OK to take money out whenever they want? No? Then why do we put up with software that thinks being invited into your computer once is equivalent to an offer to run anytime it feels in the mood?
I moaned only last week about how some programs insist on scattering shortcuts all over the desktop, even when they are only doing an update to fix some security hole. OK, so maybe I was a bit unfair picking on Adobe Reader, but in fact - as far as taking liberties with my computer - it deserves it. Did you know that it installs two programs that run every time you start your computer? One that checks for updates and one that acts as a speed-increasing pre-loader.
I suppose both are useful if you spend most of your day using Adobe Reader. I don't, however. And surely if every program you installed insisted in running some "speed enhancing loader" like this it would defeat the whole object because every program would end up running more slowly. OK, so security update check programs are a requirement these days, and hopefully terminate after doing their check, but they still hit the start-up time. Perhaps, where appropriate, they could execute the update check when the program runs instead (like Mozilla does)?
The first thing I do when asked to "look at" somebody's computer that's running slowly or taking ages to start is to consider stopping some of the three dozen or so programs that decide they need to auto-start. I suspect this is a factor in many cases where users complain that their computer is "getting slower all the time" - although some PC manufacturers are equally to blame for filling the machine with a bucketful of semi-useless demo-ware.
Of course, some vital applications, such as security and virus protection software, do need to run at start-up. Though I'm not sure Microsoft Communicator or Messenger quite qualify for the "vital" category, but at least they have menu options where you can turn off "Start when Windows starts". And some other less-than-vital applications are sensible enough to install their shortcut in the Startup section of the Start menu so you can easily find (and delete) them.
So, having moaned at Adobe, who else has the temerity to imagine that they own my computer? How about the utility for backing up a mobile phone? I installed it and used it once to back up the initial configuration of my wife's gleaming new HTC Desire phone, and ever since I've had an ugly picture of a phone blinking at me from the notification area. Just so that, in case I decide sometime next year to plug the phone in again, it can spring magically to life. Maybe it would be useful if I synchronized music and photos every day, but surely an option to not have it run all the time wouldn't be that hard to do?
And, even worse, how about the TomTom satnav utility? I don't have a TomTom satnav, but I did agree to try and upgrade/fix one for a friend. The only way you can do it is to install the HOME utility from TomTom's website. Yes it installs so that it auto-starts, and then sits grinning at you from the notification area forever afterwards. So I now have two programs that I don't want or use, for devices that I don't have, running on my computer. I know memory and processing power is cheap these days, but I don't see why I should be wasting it like this.
Of course, Microsoft is well aware of this issue. One of the useful tools in Vista was Windows Defender, which let you easily see (and stop) programs that auto-run. However, if you install anti-virus software, including Microsoft's own Security Essentials, Defender is disabled. So thank goodness for Sysinternals Autoruns (this latest version is better than ever). Using it I discovered that the HTC utility actually installs four executable files in various places, including Task Scheduler, and the TomTom utility installs two. But removing them with Autoruns is easy, without having to dive into the Registry.
Of course, there's still the usual warning about fiddling with system settings. Changing Registry settings can cause your children to die from the plague, your house to fall down, your own Mother to disown you, and you may even prevent your computer from running correctly. So don't remove anything if you are not sure what it does.
Maybe the reason manufacturers insist on auto-running programs is because they think users are too stupid to realize they need to run them themselves when required. I would have doubted that until recently, but according to recent research led by a professor at Leeds University on behalf of the British National Formulary (which advises on medicines) expecting people to be able to turn their computer on at all is now in question.
The research team have discovered that complicated instructions, such as those typically found on medicines, can "cause confusion" and "should be simplified". The examples they gave of instructions that are now "too difficult for patients to understand" are "May cause drowsiness" and "Avoid alcohol". Gadzooks! Perhaps we need to simplify our IT terminology to match? Instead of "computer" we should maybe use "box with screen and letters on it", and instead of "USB cable" we should use "bendy wire thing with funny square bit on the end".
It all reminded me of that wonderful air traffic control oriented after-dinner speech by Dave Gunson (still available from Amazon) where he explained that airliners have to follow narrow flight corridors to maximize safety and position, and that it requires highly skilled flying to maintain the correct course and route. But then spoilt it by admitting that they actually show them in colors on the map, so you just need to "go down the blue one, then the red one..."
And that pilots wear white kid leather gloves with a big black letter "L" on the back of one and an "R" on the other...