Random Disconnected Diatribes of a p&p Documentation Engineer
You may not remember, but when ASP.NET was in the early stages of development it was called ASP+. I wonder if we'll see history repeating itself so that, when it finally clambers out of beta, Google+ will actually be called Google.NET. Probably not. I guess there's too many hard-up lawyers around at the moment looking for work. But it does seem that, in many spheres of life, we never get the hang of the notion that history repeats itself.
In politics we go through regular cycles of left-leaning (run out of money) and right-leaning (no new taxes, maybe) government. With the environment we can't make up our mind whether we want nuclear (clean but dangerous) or fossil-fuelled (safe but global warming). As for the financial crisis, we're torn between printing money (more debt) and cutting spending (less growth). It's almost like history doesn't teach us anything.
So what about my own little corner of the world: technical guidance and developer documentation? It sometimes seems like the process for this is built around the concept of conveniently ignoring the lessons of history. Here at p&p, our goal is to provide guidance for developers, system architects, administrators, and decision makers using Microsoft technologies - our tag line is, after all, "proven practices for predictable results". But designing projects to achieve this sometimes seems to be history repeating itself. And not always in a good way.
The problem tends to center around how to figure out what guidance users require, and how to go about creating it. My simple take is that you just need to discover exactly what the users need, what you want to guide users towards (the technologies, scope, and technical level that is appropriate), and the format of the guidance (such as book, online, video, hands-on-labs, FAQ, and more). From that you can figure what the TOC looks like and what example code you need, or what frameworks or applications you must build to support this. So, as usual, it's all about scenarios and user stories.
In the majority of cases, this is exactly how we plan and then start work on our projects. But the problem is that it's very easy to start by throwing a bunch of highly skilled developers at a new technology and letting them play for a while. OK, so they need to explore the technology to find out how it works, and figure out what it can do. They go through the process of spiking to discover the capabilities and issues early on so that their findings can help to shape the decision process for designing the guidance and defining the scope.
However, it's very easy for developers to be influenced by the capabilities of the technology rather than the scenarios. As a writer, I ask questions such as "Is this feature useful; and, if so, when, where, and why?", "What kind of application or infrastructure will users have, and how do the technology features fit in with this?", and "Does the technology solve the problems they have, and add value?" In other words, are we looking at the technology from a user requirements point of view, or are we just reveling in the amazing new capabilities it offers?
Here's an example. When you read about Windows Azure Service Bus, it seems like an amazing technology that you could use for almost any communication requirement. It gives you the opportunity to do asynchronous and queued reliable messaging between on-premises and cloud-based applications, and supports an eventing publish/subscribe model. It can use a range of communication and messaging protocols and patterns to provide delivery assurance, can scale to accommodate varying loads, and can even be integrated with on-premises BizTalk Server artifacts.
The Microsoft BizTalk Server Roadmap talks about future integration with Windows Azure but it seems as though you could support many of the BizTalk scenarios with Azure right now using Azure Service Bus, as well as extending BizTalk to integrate with cloud-based applications. But what are the realistic scenarios for real-world users? Will developers try to retrofit Service Bus capabilities into existing applications, or does it make sense only when building new applications? Will they attempt to extend BizTalk applications using Service Bus, or aim to replace part or all of their BizTalk infrastructure with it?
And what Service Bus capabilities are most useful and practical to implement in real-world scenarios and on existing customer infrastructures? Are most developers desperate to implement a distributed publish/subscribe mechanism between on-premises and multiple cloud-based applications, or do they mainly want to implement queuing and reliable message communication? Will it mean completely reorganizing their network and domain to get code that works OK in development spikes to execute on their systems? Is there a danger that experimental development spikes not planned with specific scenarios in mind will end up being completely unrealistic in terms of being applied to today's typical application implementations and infrastructure?
I can see that playing with the technology is one way to find this out, but it's also an easy way to build example code and applications that don't reflect real-world scenarios and requirements. They aren't solutions; they can turn out to be just demonstrations of features and capabilities. This is why we expend a great deal of effort in p&p on vision and scope meetings, customer and advisory group feedback, and contact with product groups to get these kinds of decisions right from the start.
And let's face it, there are several thousand other people in EPX here at Microsoft writing product documentation, each focused on their own corner of the technology map and concentrating on their own specific product features and capabilities. So it's left to our merry little band here in a forgotten corner of the campus, and scattered across the world, to look at it from an outsider's point of view and discover the underlying scenarios that make the technology shine. Finding the real-world scenarios first can help to prevent the dreaded disease of feature creep, and the wild exuberance of over-complexity, from burying the guidance in a morass of unnecessary technological overkill. And that's before I can even start writing it...
And just in case, as a writer, you are feeling this pain here's some related scenario-oriented diatribes:
So the Edinburgh Fringe Festival ended last week and, as usual, they announced the winners of the under twenty seconds joke category. The winner, it seems, was Nick Helm's contribution of "I needed a website password containing eight characters, so I used SnowWhiteAndTheSevenDwarves". Oh dear. And second was Tim Vine with "Crime in multi-storey car parks - that's wrong on so many levels". Yet it made me realize just how much of a waste of time my recent web administration tasks probably were.
Several years ago we set up a website for our village resident's action group. It's a lively site that displays news, weather, events, photos, and other generally useful local information. We set it up with membership capabilities so people can register to keep in touch, and to read committee reports and meeting minutes. It was adapted from a very old version of the ASP.NET Club Starter Site, much modified to our requirements.
However, it also used the default personalization and security settings, storing passwords and answers to security questions as plaintext in the database. We never really considered this to be a major risk because, even if you got hold of somebody else's login details, you'd only get to see the list of members and the committee meeting minutes. And you can do that just by registering anyway.
But I've always been a bit nervous about this, and with the increasing number of attacks and stolen credentials we seem to be hearing about these days, I needed to do something about it. Especially as I suspect many people, despite the large warnings we show on the Register and Login pages, use the same password for every website they visit - including their online bank.
Of course, changing the password storage mode is easy; you just switch the attributes in the web.config file to turn off "retrieve password", turn on "reset password", and specify "hashed" or "encrypted". Except that it only affects new accounts. I experimented with both existing and new accounts, and discovered that even resetting the password doesn't change the mode for an account. So I played with creating a script to update them, but never managed to get it to generate a hash that was the same as the membership system would create for the same user.
In the end, the only solution seemed to be to delete and recreate all of the accounts. The existing accounts need to be deleted first so that the new ones can use the same username and email address, so I can’t just get people to re-register whenever they like. Thankfully there aren't that many accounts, so in the end I decided to manually re-register them all myself. Users won't see any difference, and I can do them one by one in any periods of spare time I can find to devote to the task.
Of course, to do this I needed to read the existing details of the user, including the security question, answer, and password. I'm not sure of the legal position here, but there seemed no other workable option and I would only be copying them from a database table into a text box so it seemed safe enough. At my senility-approaching stage of existence, I'd never be able to remember any of them anyway - even under torture (such as being locked in a cold room with no access to chocolate).
And it's here that the "wrong on so many levels" bit hit home. I only saw one password that was even remotely complex; every other was a simple dictionary word, occasionally with a number or two on the end (but I suppose I should be pleased that nobody used "password" for their password). As for the security questions and answers, most were typical pet, child, or mother's maiden names. Though a few were somewhat less secure - "Colour of my front door" (when they also put their address on public view in the membership pages) being a typical example.
And what really amazed me was one where the question was "What is 1 plus 2?" OK, if the security answer had been "79" I would have applauded them for originality, but sadly their answer was "3". I know that the mechanism emails the password reset code only to the registered email address, but this seems to be someone intentionally flaunting our attempts to help them stay secure. Or, perhaps more likely, not actually understanding what they are doing.
Still, now everyone has a hashed password and security answer in our database, and I feel a lot more comfortable. I even updated the Privacy page to add the recommended disclaimers and explanation of what we do with their personal information. And I also added the stuff that the People's Republic of Europe now demands about storing cookies on user's browsers.
In case you hadn't heard, the faceless bureaucrats of the State Of Europeland now demand websites obtain consent from visitors to store cookies in their browser. Supposedly it doesn't include cookies "necessary to enable websites to work correctly", though how that is defined nobody seems sure. I'm guessing that they realize what will happen if they ban use of the ASPNET session cookie. And it's not like banning something will have any effect on the visitor-tracking and other malicious practices already in use on the web. Let's face it, most users don't actually care that much about privacy anyway...
But what's really worrying is if the kind of behavior I've seen in the last few weeks with regard to passwords and general security awareness is typical. If so, we really do need to do something to help people protect themselves from themselves. Thankfully most sites that do contain sensitive information now demand complex passwords, but I still know of at least two people who - despite my nagging - insist that a single dictionary-word password is enough for all their accounts.
Meanwhile, the third prize (in the joke competition - keep up at the back) was "People say 'I'm taking it one day at time'. You know what? So is everybody. That's how time works." In fact, I reckon that one should have won...
Footnote: British readers (who know what B&Q is) will perhaps not be surprised to hear that our favorite comedian and magician Paul Daniels came last with "I said to a fella 'Is there a B&Q in Henley', and he said 'No, there's an H and a E and an N and...'"
FootFootnote: The title of this week's rambling is from the radio show that inspired not only Edinburgh Fringe Festival, but also most other comedy revue shows since then.
Britain's roads are, they say, becoming a monochrome and sadly boring reflection of the past. It seems that some 90% of cars on the road today are black, grey, silver, or white. Yes there are some very dark blues out there as well, but overall it does seem to be true. My wife's most recent choice of car was based mainly on the fact that there are hardly any bits (including the windows) that aren't black. Though the fact that it also goes very fast was, I suspect, a contributing factor.
And I can't dispute the assertion of monochrominity. Other than a bright yellow Renault 5 when I was very much younger, all my previous cars were either white or silver. Mainly it's because, in my days as a traveling salesman, I always hankered over a white BMW 525i like those that regularly cruised past me as I ranged far and wide across our green and pleasant land. You could see the barely disguised traces of style and quality, with the promise of amazing levels of comfort and performance, as they glided by with the driver managing to simultaneously look down on my lesser mode of transport whilst maintaining an air of superiority.
Mind you, in the early days of that career path the companies I worked for did provide quite reasonable vehicles - what would now be referred to in the US as midsize middle-of-the-range models, such as the 1600cc Ford Cortina and Vauxhall Cavalier. Nice motors, though without features such as air conditioning, parking sensors, and all the other fancy bits that are pretty much standard these days. And we even managed without mobile phones and satnav (mainly because they hadn't been invented then).
However, towards the end of that part of my life the gradually reducing profits of my trade were reflected in the quality of the car. My last employer, before I finally abandoned my itinerant career to become a full-time technical author, was owned by a group that also included a car dealer; and so I ended up with a 2 litre Nissan Primera as my final company car. Real diesel cars in those days were called "turbo-diesels", but my Nissan had no such lofty aspirations. It was just a "diesel".
From a standing start, the house-brick-like acceleration could whisk you to 60 miles per hour in around 25 seconds, and you had to change down to third gear on a motorway if there was the slightest uphill gradient. At traffic signals I would have 40-ton trucks hooting at me to get a move on as I valiantly fought with the gears and pedals to try and achieve an escape velocity of 30 mph. And if, in a sudden fit of courtesy I gave way to somebody at a junction, it would add twenty minutes to my travel time so I was late for my appointment.
I don't recall ever hating a car as much as I did that one, and I suspect it played a large part in my decision to make a career change. Of course I was convinced that I could break it, thus demonstrating to my employer that is was an entirely inappropriate choice of vehicle for a salesman, but even that proved impossible. Driving 150 miles to London flat out in third gear had no appreciable effect on the thing, and it never missed a beat when I skipped every service and didn't put any oil in it for 20,000 miles. My efforts had about the same destructive effect as firing a pea-shooter at an elephant.
In the end, just before I left, I unintentionally managed to bump into the back of a large and very old Volvo at a roundabout. The driver examined the small scratch on their rear bumper (fender) and drove off. I, meanwhile, delivered my car to the local Nissan repair shop to discover that the shunt had managed to shorten it by nearly an inch, and it would cost a couple of thousand pounds to repair. So I rented a very nice little Ford Escort while it was away and spent several idyllic weeks zooming around the countryside in what, compared to the Nissan, seemed like a racing car. I even managed to forget that the repair people had phoned to say my car was fixed, and kept the Escort for another three weeks before my boss noticed and made me switch back.
I think the only saving grace was, after I left, the hated vehicle became the company's pool car so that - when my boss's rather luxurious motor suffered a catastrophic engine failure - he had to spend three weeks driving the Nissan. After that they went to leasing cars instead, and gave the reps a choice of make and model. But I can almost guarantee that, 15 years later, the Nissan is still chugging around the country delivering urgent replacement product to customers or ferrying quality control inspectors on site visits.
And now, in my dotage-approaching years, I finally achieved those boyhood dreams of owning a white BMW. OK, so it's not a 525i - surprisingly I went for a diesel one, though it comfortably out-performs anything I've had before. The strange thing was that, when I bought it some years back (see So, I Just Bought a Car from a Lady Prison Officer), it seemed like nobody in their right mind would buy a white one. Yet when the sales lady showed me the pictures I couldn't resist. I suspect that her single aim in the car sales segment of her variable career was to sell some unsuspecting punter a white one; perhaps confirmed by the fact that she left shortly afterwards.
But what amazed me was that, within only a few months, the dealer's showroom was full of white ones. Maybe the manager saw mine when it was delivered and suddenly recalled his own boyhood dreams. And when we recently visited an Audi dealer in Nottingham, every car in their showroom was white. So maybe I started a trend. Could it be that, after all, I'm partly to blame for our monochrome motorways, drab driveways, and colorless streets...?
The editions of my daily newspaper that I most look forward to are those when my favorite columnist, Bryony Gordon, is in attendance. As an example, in her Notebook column a couple of weeks ago she happened to mention that not only has her own cat posted a birthday greeting to her on her Facebook wall, but she is also following the tweets from somebody's bicycle.
OK, yes, I do take a "highbrow" newspaper; mainly because I can't cope with the relentless excitement of the tabloids, or suffer their lowest-common-denominator coverage of important events. Maybe it's also down to the fact that they feel the need to print long or difficult words in a bold typeface, edit the stories to accentuate their own agenda, and take advantage of every opportunity spread wild panic amongst their readership.
Yet, even though the Daily Telegraph does actually print real news, it's often still fun to read. The humor in the letters page is surprisingly refreshing, especially if you follow the trends from day to day. And Matt, their political cartoonist, simply can't be beaten. His contribution to the editorial spread about the News of the World's alleged phone hacking and police bribery scandal was a picture of a police van with a sign on the back saying "No payments kept in this vehicle overnight". Wonderful.
However, we need to get back to the tweeting theme. Why would anyone set up a Twitter account for their bicycle? The suggestion is so that they can send messages to it such as "I'm coming to pump up your tyres." Maybe they also set up one for their microwave oven that tweets when the dinner is cooked? Or one for their pet budgerigar so it can tweet (sorry about that) when it's hungry?
Ah, but maybe there is an upcoming trend here, and a new remote control opportunity for hardware and software vendors. By making their products tweet-aware (tweetable?) users could simply fire up a Twitter client on their phone or laptop and fine-tune their web server farm or administer their DNS entries remotely using a new standard protocol. We could call it H-Tweet-Tweet-P. Maybe even use it to install a new version of Windows, or fire up an additional VM to cope with increased demand for online applications. "All happning heer, need xtra server on line. Start, Admin Tools, Hyper-V, Alt-F, Run, OK."
And your computers could expose their status and management information over H-Tweet-Tweet-P as well. All you'd need to do is follow your servers in your Twitter app - no need to shell out hundreds of dollars on System Center or some other fancy remote monitoring software. Imagine the scene on some idyllic foreign beach, with the sun shining and the waves lapping at your feet, when the geek next to you reads "Hi, server 27 here, hope you having gr8 holiday. Just letting you know I can't find NTLDR...".
Meanwhile, the best thing of all about the Daily Telegraph is that it's the only broadsheet on the market now, so I'm one of the shrinking minority of people who can fold and turn the pages of a proper-sized newspaper without having to spread it out on the floor every time - even on an airplane. Let's face it - everyone should strive to acquire at least one useful life skill...