Random Disconnected Diatribes of a p&p Documentation Engineer
One of the joys of being a documentation engineer is the variety of projects I tackle. At the moment I'm sharing my time between two projects at diametrically opposite ends of the complexity and target audience spectrums. It even seems as though it requires my brain to work on different wavelengths at the same time. It's almost like a Rainbow Coalition, except that there's only me doing it.
For the majority of my working week I'm fighting to understand the intricacies of claims-based applications that use ASP.NET, WCF, and WIF; and to create Hands-On-Lab documents that show how you can build applications that use tokens, federated identity, and claims-based authentication. In between I'm writing documents that describe what a developer does, the skills they require, and the tools and technologies they use for their everyday tasks.
What's worrying is I'm not sure I really know enough about either of the topics. Claims-based authentication is a simple enough concept, but the intricacies that come into play when you combine the technologies such as ASP.NET sessions, browser cookies, WCF, WIF, ADFS, and Windows Azure Access Control Service can easily create a cloud (ouch!) of confusion. Add to that interfacing with Windows phone and, just to make matters even more complicated, SharePoint Server, it's easy to find yourself buried in extraneous detail.
What became clear during research on these topics was why some people complain that there is plenty of guidance, but it doesn't actually tell you anything useful. I must have watched a whole week's worth of videos and presentations, and got plenty of information on the concepts and the underlying processes. But converting this knowledge into an understanding of the code is not easy. One look at a SharePoint web.config file that's nearly 1000 lines long is enough to scare anybody I reckon. Simply understanding one area of the whole requires considerable effort and research.
Contrast that with the other task of describing what a software developer does. If you ask real developers what they do, chances are the answer will be something like "write code" or "build applications". Yet when you read articles on how development methodologies such as agile work, you soon come to the conclusion that developers don't really have time to write code at all. Their working day is filled with stand-up meetings, code reviews, customer feedback consultations, progressive design evolution, writing unit tests, and consulting with other team members.
And what's becoming even more evident is that everything now is a cross-cutting concern. At one time you could safely assume that someone using Visual Basic was writing a desktop application, and that the developer using ASP.NET was building a website. Or the guy with a beard and sandals was writing operating system software in C++. Now we seem to use every technology and every language for every type of application. Developers need to know about all of them, and weave all of the various implementation frameworks into every application. And find time to do all that while writing some code.
For example, just to figure out how our claims-based examples work means understanding the ASP.NET and C# code that runs on the server, the WCF mechanism that exposes the services the client consumes, the protocols for the tokens and claims, how ACS and ADFS work to issue tokens, how they interface with identity providers, how WIF authentication and authorization work on the client, and how it interfaces with the ASP.NET sessions to maintain the credentials. And don't get me started on the additional complexities involved in understanding how SharePoint 2010 implements multiple authentication methods, how it exposes its own token issuer for claims, and how that interacts (or, more significantly, doesn't) with SharePoint groups and profiles.
At one point in the documentation about developer tasks, I started creating a schematic that maps development tools, technologies, and languages onto the four main types of application: web, desktop, cloud, and phone. It starts out simple enough until you realize that you forgot about Silverlight and XNA, or still need to find a slot for FxCop and the Expression Blend. And where do you put the Microsoft Baseline Security Analyzer? Meanwhile, Visual Studio seems to be all things to all people and to all tasks. Until you try to divide it up into the full versions, the Express editions, and the special editions such as the one for Windows Phone or the add-ons for WIF and Windows Azure. I don't think anybody has a screen large enough to display the final schematic, even if I could manage to create it.
And just like Rainbow Coalitions in government, it sometimes seems like there are lots of different actors all trying to present a single face to the world but, underneath, all working to a different script. Should I use Razor in WebMatrix for my new website, or MVC, or just plain old ASP.NET Web Forms? Is WPF the best technology for desktop applications, or should I still be using Windows Forms? Or do it in Silverlight in the browser. And in which language? It's a good thing that, here at p&p, we provide plenty of guidance on all these kinds of topics.
Still, at least I can create my technology matrix schematic using all of the colors of the rainbow for the myriad boxes and shaded sections, so it actually does look like a rainbow and provides a nice calming desktop background - even if it does nothing else more useful.
If I asked you what they manufacture in Seattle, I'd guess you'd say "software and aeroplanes". Obviously I'm biased, so Microsoft is the first name to spring to mind. And I discovered from a recent Boeing factory tour that they build a few 'planes there now and then. You might also, after some additional thought, throw in "coffee shops" (Starbucks) and "book stores" (Amazon). But I bet you didn't include "doorbells" in your list.
I know about the doorbells because I just bought a SpOre push button from a UK distributor and it proudly says "Made in Seattle" on the side of the box. Unless there is another Seattle somewhere else in the world, I'll assume that somebody expert in working with aluminium got fed up nailing wings onto 747s and left to set up on their own. Though you have to wonder about the train of thought when creating their business plan. "Hmmm, I'm an expert in building massively complex, high-tech, hugely expensive pieces of equipment so I think I'll make doorbells..."
But the point of this week's wandering ramble is not specifically doorbells (a subject in which, I'll admit, I'm not an expert). What started this was the time and effort required to actually find the item in the first place. We don't live anywhere near a city that contains one of those idiosyncratic designer showrooms, and I tend not to spend my weekends at building exhibitions. So, when my wife decides that she wants "something different" in terms of hardware, furniture, or other materialistic bauble that the average DIY store doesn't stock, I typically end up trailing through endless search engine results trying to track down products and suppliers.
Inevitably, what seems like an obvious set of search terms fails to locate the desired items. For example, rather than the usual "black plastic box and white button" that typifies the height of doorbell-push style here in England, searching for "contemporary doorbell push" just finds tons of entries for shopping comparison sites, ugly Victorian-style ironmongery, a few rather nasty chrome things, and (of course) hundreds of entries on EBay. I finally found the link to the SpOre distributor on what felt like page 93.
Much the same occurred when searching for somebody who could supply a decent secure aluminium front door to replace the wooden one we have now (which was already rotting away before the ice-age winter we just encountered here). It took many diligent hours Binging and Googling to find a particularly well-disguised construction suppliers contact site, which linked to a manufacturer in Germany, who finally forwarded my email to a garage door installation company here in England. When I looked at their site, it was obvious that they did exactly what we wanted, but there was pretty much zero chance of finding them directly through a web search.
And, not satisfied with all this aggro, it seems that the door manufacturers in Germany won't put a letter box slot in the door. They can't believe that anyone buying a properly insulated secure entrance door would want to cut a hole in it just for people to shove letters though (they tell me that only people in the UK do stupid things like this), so I have to figure out another way to provide our post lady with the necessary aperture for our mail. The answer is a proper "through the wall post box", and I'll refrain from describing the web search hell resulting from locating a UK supplier for one of these.
Of course, the reason for the web search hell is that I don't know the name of the company I want before I actually find it. If I search for "spore doorbells" or "hormann doors", the site I want is top of the list. Yet, despite entering a bewildering array of door-oriented search terms, all that comes up unless you include the manufacturer's name is a list of double-glazing companies advertising plastic panelled doors with flower patterns; or wooden doors that wouldn't look out of place on a medieval castle.
The problem is; how do you resolve this? There are obviously lots of very clever people working on the issue; and for website owners the solution is, I suppose, experience in the black art of search engine optimization (SEO). But there are only a limited number of obvious generic search terms - none of which are unique - compared to the millions of sites out there that may contain marginally relevant content. It seems that only searches for a product name (a registered trade mark) can really get you near to the top of the list. Even the sponsored links that most sites now offer are little help unless you can afford to pay whatever it costs to get your site listed whenever someone searches for a non-unique word such as "door". Meanwhile, most product and shopping comparison sites are more about how cheap you can buy stuff than helping you find what you are looking for.
One alternative is the tree-style organization of links. When done well, this can be a great way to help you find specific items. Most search engines have a Categories section that allows you to narrow the search by category, but the logic still depends on how the search engine analysed the page content. It's really just an intelligent filter over the millions of matching hits in the original list of results. It's easier, of course, if you only need to find something within a site that can manage the content and categorization directly. An example is the B&Q website at http://www.diy.com - and when you consider the vast number of lines they stock it makes it really easy to navigate down through the categories to find, for example, 25mm x 6mm posidrive zinc plated single thread woodscrews.
Mind you, tree navigation is not always ideal either. Some products will fit well in more than one category, while others may not logically fit into any category other than the useless "Miscellaneous" one. And once the tree gets to be very deep, it's easy to get lost - even when there is a breadcrumb indicator. It's like those automated telephone answering systems where you only find out that you should have pressed 3 at the main menu instead of 2 once you get two more levels down. And then you can't remember which option you chose last time when you start all over again. But at least with a phone system you can just select "speak to a customer advisor...".
I remember reading years ago about the Resource Description Framework (RDF). Now part of the W3C Semantic Web project, RDF has blossomed to encompass all kinds of techniques for navigating data and providing descriptive links across topic areas. It allows you to accurately define the categories, topics, and meaning of the content and how it relates to other content. So a site could accurately specify that it contained information in the categories "Construction/Doors/Entrance/Residential/Aluminium/Contemporary" and "Building Products/Installers/Windows and Doors/Residential/". And, best of all, RDF supports the notion of graphs of information, so that an RDF-aware search engine can make sensible decisions about selecting relevant information.
Yet it's hard to see how, without an unbelievably monumental retrofit effort across all sites, this can resolve the issue. It does seem that, for the foreseeable future, we are all destined to spend many wasted hours paging and clicking in vain.
Have you ever wondered what insurance companies do with all the money you pay them every month? It seems that one UK-based insurance company decided that a good way to use up some of the spare cash was to discover that, every day, people in the UK are carrying around over 2,000 tons of redundant keys. I'm surprised they didn't come up with some conclusion such as this requires the unwarranted consumption of 10,000 gallons of fuel, which emits enough carbon to flood a small Pacific island.
It seems they questioned several hundred people about the number of keys they carry and which locks they fit, and the results indicate that everyone carries around two keys that they don't know what they are for. However, I did a quick survey amongst six family members and friends and discovered only a single unknown key amongst all of us. So, on average, we are only carrying one sixth of an unknown key around. Extrapolating this percentage across the country means that there must be several hundred people carrying bunches of keys around when they don't know what any of them are for.
Of course, statisticians will tell you that you can't just average out results in this way - it's not mathematically logical. It's like saying that, because some cats have no tail, the average cat has 0.9 tails. Yet insurance companies rely on averages every day to calculate their charge rates. They use the figures for the historical average number of accident claims based on your age and driving record, or the average number of claims for flooding for houses in your street. Or your previous record of claims for accidental damage to your house contents.
What's worrying, however, is how these numbers affect your premiums. I just changed the address for my son's car insurance when he moved a quarter of a mile (to the next street in the same town) and the premium came down by nearly a quarter. I've suggested that he move house every month so, by next year, we won't be paying anything. Though it probably doesn't work like that...
Anyway, if the way they calculate premiums is already this accurate, just think what it will be like in a few years' time as more powerful processors, parallel algorithms, and quantum computing continue to improve the prediction accuracy. The inevitable result is that, when you apply for an insurance quote, the company will actually be able to tell exactly how much they will need to pay out during the term, and will charge you that plus a handsome profit margin. So you'll actually be better off not having insurance at all, and just paying the costs of the damage directly!
And this is the interesting point. Insurance is supposed to be about "shared risk". When insurance first started after the severe fires in London in the 17th Century, the premiums were based on the value of the property and the type of construction. Wood houses cost twice as much to insure as stone or brick houses. Other than that, everyone paid the same so they shared the costs equally. Of course, you can't really argue with the concept that people who have lower risk should pay less, or that people whose property is more valuable (and will therefore cost more to replace) should pay more. But I wonder if we are starting to take this to extremes.
Ah, you say, but even with the pinpoint accuracy of the current predictions of risk, they are still averages. So if you are lucky (or careful) you can beat the odds and not need to claim, while if you are unlucky (or careless) you will get back more than you paid in premiums. True, but next year they'll just use an even more powerful computer to recalculate the risk averages. Like a derivative function in calculus, the area of variability under the curve can only get smaller.
But I suppose it will be useful in one respect. When you get your motor insurance renewal telling you that this summer you will collide with a 2004 registered blue Volkswagen Beetle at a traffic signal in Little Worthing by the Sea, you can simply cancel your policy and use the money you save to go on holiday to Spain instead.
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...
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...
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'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've been struggling with the meanings of words again this week. Partly it's because I'm not a native US-English speaker, and partly it's because I tend to make wild assumptions about the way that the major IT hardware companies view their customers. I suppose I could buy a US-English to Queen's English phrase book to solve the first issue; and take more notice of website product reviews to resolve the second...
So, starting this week with a diatribe, consider how you would implement the web page for managing a device that allows you to specify optional settings (note the word "optional" - it's relevant later on). Let's assume that the setting in question is an IP address, and you provide four text boxes - one for each of the IPv4 sections of the address. And assume that you have added some client-side widget that validates the entries in each box and forces them to be a number between 0 and 255. All make sense so far?
Now remember the key word in this scenario: "optional". What happens when your users realize they made a mistake and want to remove the IP address? If you own a one of those routers that provide "a platform that is ready for service" (such as the 527W), what happens is that you can't. It seems like you are stuck with them for eternity (or until you toss the thing against the wall in frustration). You can't delete them. If you disable scripting and Java stuff the page doesn’t work at all. And, before you ask, the most recent firmware upgrade doesn’t fix it - in fact it doesn't even mention it in the "Known Issues" document. Neither is there a mention of it anywhere I can find searching the web. Obviously I'm the only person in the world who has ever tried to do this.
Ah, but when you go to the router's support site you get a nice pop-up Chat box so you can ask your question. And their answer? Here's an abridged version: "To get support from us you need a support contract. If you had purchased it from one of our partners you could get advice from them, but as it was purchased from Amazon there is no support unless you take out a support contract. Unfortunately you have chosen to buy from a grey market." I wonder if Amazon knows that they are a "grey market". And who would buy a support contract for a router than costs less than $200 ?
Anyway, after I finally decided to do a full reset and completely reconfigure it (there was no wall nearby to throw it at) I discovered that setting the optional DNS entries to 0.0.0.0 means that the router will just ignore them. All I can say is that it would have been nice to see this mentioned in the manual...
But I guess I should get to the original point of this post and mention my "US-English" problem. In between the tasks of my day job I've been creating some exercises that describe using Web Matrix to build a reasonably full-featured website for a soccer club. The topic of soccer wasn't my idea - it was part of the brief and I assume it's because soccer has a more universal international appeal than (American) football.
I realize that they call it "soccer" in the US to differentiate it from their version of "football" where you actually carry the ball around rather than kicking it - a bit like playing rugby in a suit of armour (or should I say "armor" - you can see how difficult this gets). What I didn’t realize is that in the US they have also changed all of the words associated with soccer. It's like it's been US-ized so that common soccer-related terms are made to sound like rude words.
The obvious example was the horror that spread across reviewers faces as they read about the fact that the players were trying out "a new team strip". I think they had visions of all the players running around naked. And when they came to the bit about "coping with a muddy pitch" they asked what the players were pitching for, or if I meant they picked the ball up and threw it. And when I talked about a "local derby", they asked if there were horses on the pitch as well...like it had morphed into some strange kind of polo match.
Likewise, when a news item on the site revealed that they were moving to a new clubhouse "due to a local road improvement scheme", I was told that something is a "scheme" only when there is nefarious or illegal activity going on. And that the list showing upcoming "fixtures" sounded like it should be full of things you nail on a wall or screw to the floor.
I wonder if it's time we took a stand and against all this. Though that probably reads like I want somewhere for the spectators to congregate to watch the match. Even though, in a "stand", you actually sit down. Oh well, I suppose it's all our (Queen's-English) fault really...