Random Disconnected Diatribes of a p&p Documentation Engineer
One of my previous jobs involved travelling to a variety of locations selling things. Amongst those locations was the British Rail Engineering works (BREL, more familiarly known as just "The Plant Works") in Doncaster, South Yorkshire. It was one of those amazing old Victorian factories where you felt like you had stepped back 100 years as soon as you walked into one of the huge old brick buildings. It reeked of history and those wonderful engineering aromas of cutting fluid, oil, engines, and ancient machinery.
But getting inside was, to a geek or trainspotter, like finding the Holy Grail. And I was lucky, one day in April 1979, to be taken - complete with camera - on a private guided tour. So, if you are interested in railways, you may just find the following photos and notes interesting...
At the time, the works was building the Class 56 freight locos. Here you can see the assembly line, the power plant, the assembled loco, and the finished result:
The works also refurbished diesel multiple units. Here are before and after views:
BREL maintained the Deltic fleet. Unfortunately, they were short of one engine so there was always one Deltic sitting forlornly in the yard - in April 1979 in was 55 020 "Nimbus". In the photo here, 55 015 "Tulyar" is undergoing refurbishment.
Another section of the works was, during 1979, refurbishing the "Hoover" class 50 locos, which operated mainly on the Western Region at that time. The photo shows 50 043 "Eagle" ready to go back to work, with Class 31/1 number 31 301 alongside in for running repairs:
Some of the class 50s managed to bring forward their planned refurbishment. This is 50 003 "Temeraire" awaiting some serious attention after a collision:
And, of course, more than a few locos ended their life as spare part donors:
And that's enough railways. Next week look out for (as Monty Python always used to say) something completely different...
Let's face it, those of us who work in the hi-tech world of computing tend to think of ourselves as being - well, not to put too fine a point on it - intellectual; even skilled artisans of our trade. We string lumps of extremely complex hardware together so they can talk to each other, write clever code that executes mind-boggling tasks in the blink of an eye, and build wonderfully intuitive and interactive interfaces for our applications. And all before lunch some days.
Yet once you step outside of our world of information technology to accomplish something far more down to earth, such as a task that is practical in terms of most people's day to day lives, you suddenly realize just how little our skills have in common with the real tradesmen (and women) of this world. How something that seems like it should be really simple, compared to software design patterns and administering enterprise systems, is really much harder to do well than firing up Visual Studio and tossing it some code, or plugging network cables into a server and setting up the DNS.
OK, so I'm no great programmer. My IT skills tend to come into play further down the line, after some of the really clever people around here write the code. But, as I discovered, I'm not much of a carpenter or plasterer either. When you watch real skilled artisans at work, it seems like what they do is simple - until you try it yourself. I reckon these people are really artists rather than just artisans. They apply the techniques of their trade with an artistic flourish that belies the skills, years of practice, and experience required.
Like most DIYers, I realize that it's reasonably easy to achieve a semi-professional outcome with some jobs. I can paint a door so there are no drips, blobs, or patches. I can do plumbing and house wiring with a confidence that it will work afterwards. I've even done gas fitting when we fitted out a kitchen some years ago, though I did get that tested by a professional afterwards. And I can usually mend simple stuff that breaks. I can even cut glass and do glazing work (after spending several years working with greenhouses for a garden supplier).
So when we took the old gas fire out a few weeks ago (see Firing Up the Imagination) and it left a two foot square hole right through the wall to the outside, I reckoned I could do most of the work to put it right. OK, so I have a pal who is a builder and I let him brick up the hole (I know for a fact that the art of bricklaying is not one of my proficiencies). But surely plastering up the remaining bit and putting on some new skirting board can't be that hard?
Oh yes it is. Even after three attempts and half a roll of sandpaper to try and get rid of the bumps and rough edges, it still looks like someone threw a rice pudding at the wall. Luckily the new fire covers most of it. And simply fitting a new chunk of skirting board into the gap between the existing pieces took hours of work. Mind you, it didn't help that the new piece has a slightly different profile to the existing stuff. But even careful shaping, delicate lining up, and half a tub of filler (plus, of course, the rest of the roll of sandpaper) couldn't make it blend in.
The trouble is; what else do you do? Have you ever tried to find a plasterer who will come out and plaster a hole two feet square? Or a carpenter who will pop in and fit three feet of skirting board? Usually all you get is laughter at the other end of the phone. I suppose it's like asking a developer to come round just to rename a couple of variables in your code, or calling out an admin guy in the middle of the night just to reboot your laptop. Or even getting your tame documentation engineer to change the formatting of two words in the middle of a huge help file. Err... just a minute - I have to do that all the time. So maybe I'm an artist after all...
I was reading a story (a.k.a. urban myth) this week about an eminent quantum physicist who was stopped for speeding in his car. When told by the traffic cop that he was doing 63 miles per hour, he responded by asking if this was an accurate measurement. Being told that it was he explained that, therefore, they could not definitely determine if he was inside the 35 miles per hour zone at the time. Alternatively, if they were sure that he was within the zone, it was physically impossible - due to the fundamental laws of quantum mechanics - for the speed measurement to be accurate.
OK, so the story was phrased a little more colloquially that this. When asked if he knew how fast he was travelling, the eminent physicist replied "No, but I know where I am". Of course, our eminent physicist was simply explaining that, according to the Heisenberg uncertainty principle, it is impossible to simultaneously determine the precise values of certain pairs of physical properties, such as position and momentum, of an object.
It's an interesting theory; and you may want to ponder if, when you measure the transfer rate of your high speed Internet connection or the performance of a new super fast hard disk, the results actually apply to your neighbor's DSL line or your wife's laptop instead. Although in reality this effect only reveals itself where you are dealing with very small or very fast things. Perhaps if I write this blog post using 6 point Arial, and type fast, there's a danger that the text might end up in a different paragraph, or even a different document.
And as for really small and fast things, you don't get much better than the electrons that make up the ones and zeros of your latest and greatest computer programs. So there's definitely a danger that, if you make your new enterprise application run too quickly, you won't be able to tell which server it's running on when you come to do performance testing. Probably a good argument for installing a server farm.
And does this uncertainty extend to other pairs of physical properties? Can I argue that my spelling is so bad because it's impossible to determine the actual alphabetic letter and its position within a word at the same time? Or insist that my BMI must be around 25 because it's impossible to simultaneously measure my weight and height? Perhaps if I was also running very fast at the time it would work.
However, what's really disappointing is that Heisenberg's principle also puts paid to my idea for becoming a millionaire by patenting a device for removing the space junk that I keep reading is increasingly endangering satellites and space craft in Earth orbit. I'd just finished the design for a rocket fitted with a large magnet when I read that most of the junk is travelling at six miles per second - which probably means that I can't determine how big the chunks are. So how would I know what size magnet I'd need?
A holiday weekend, and it rained. What a surprise. Still, it meant I actually got round to fulfilling a promise from a few weeks ago about firing up the film scanner and digitalizing some of the better ones of my collection of old railway slides. So, if you are not a railway fanatic maybe should stop reading now and find some other technical blog about computers (or play another game of FreeCell). The rest of this post is just pictures of old trains...
By way of some background to my pre-computing geekiness, my trainspotting episode started in around 1965 when steam was in the last stages of giving way to diesel. Most of my memories of steam engines are seeing them passing through Gloucestershire on their sad and final trip to the scrap yard in Barry, South Wales. However, my real passion in those days was for the gleaming new diesel hydraulic Western and Hymek locos that thundered past our house. Though travelling the world and the UK with parents serving the Royal Air Force meant that I lived (and trainspotted) in a variety of locations. Unfortunately, it was only in the late 70's that I owned a good enough camera to start recording what I saw.
Since then, trains have become a minor peripheral part of my life as marriage and work (and growing up) took over. So I can't actually provide a detailed history or record of any one period. Though occasional day trips to preserved railways and (now derelict) railway infrastructure and installations does provide the occasional fix. Still, here's a selection of the resulting digitalized memories:
British Rail Class 9F 92220 "Evening Star". The last steam loco built by BR (in 1960), and now preserved as part of the National Collection.
GWR 7812 "Erlestoke Manor" built at Swindon works around 1938, seen here in 1980 approaching Highley on the Severn Valley Railway.
LMS "Black Five" 5305 leaving York with a steam special in around 1980. Now refurbished and running on the Great Central Railway.
British Railways 73050 "City of Peterborough" built in Derby in 1954 and seen here in 1987 at the Nene Valley Railway.
Class EM1 76007 and 76008 built in 1953 and seen near Woodhead Tunnel on the Manchester-Sheffield route around 1978, shortly before the line was closed.
Diesel Hydraulic "Western" class D1062 "Western Courier", built at Crewe in 1963 and seen here on the Severn Valley Railway in 1980.
An unidentified "Brush" class 47 leaving Peascliffe Tunnel on the East Coast Main Line in 1979 before electrification of the route.
The "Deltic" Class 55, the most powerful of the mainline passenger diesels and my personal favorite of all diesels. This is 55 003 "Meld" built in 1961 at the Vulcan works in Newton-Le-Willows and named after a famous racehorse. Seen here at Doncaster in 1979.
British Rail adapted some of the 08 class shunters to work as tandem units in Tinsley Yard, Sheffield. This is 13 001 seen in 1979 on the yard hump.
An unusual visitor to Doncaster, having just left the BREL works after refurbishment. Originally built in 1968 at the Vulcan works, this is class 50 007 "Hercules" (later renamed "Sir Edward Elgar"). The locos were often known as "Hoovers" due to the sound of the large engine room fans.
And finally, for U.S. readers and tram fans, New York Third Avenue Transit number 674 seen here on a rainy day in June 1990 at Crich Tramway Museum in Derbyshire (just a few miles from where I live).
I also found a selection of slides taken inside the British Railways Engineering (BREL) works at Doncaster in 1979. After I sort them out, I'll post a few of the more unusual ones...
Two thousand and ten is, they say, the year of the Cloud. Yes, I know they've been saying that for a few years, but it really does seem to be a technology that is heading skywards (ouch, sorry) this year. And I'm about to climb on board. Though, hopefully, not equipped with pan pipes or tendering my CV to St. Peter. I've finally managed to dig an escape tunnel and flee the clutches of Enterprise Library 5.0 now we've got the Hands On Labs done, and before they think of anything else I need to write about.
And just to prove that this is the start of something big, all the global sales teams here at Microsoft were treated to a special presentation and training event about how it changes the whole technology business paradigm (or something marketing-speak like that). Meanwhile, I'm just starting to catch up on the Windows Azure Guidance (WAG) project here at p&p. A project that I should have been working on for the last three months. So I need to do some serious "accelerated learning", as they call it in the trade.
However, even though I work for p&p in Redmond, I live in England and am employed by Microsoft UK. Which is functionally part of the sales and marketing group (SMG). And, therefore, the exciting Cloud Training event is mandatory for all staff. OK, so usually I just keep my head down when SMG stuff is floating around, but this time they are monitoring take-up (and there is a test at the end) so I did the online version of the training this week. And I'm still recovering. Normally, training for my role involves placid activities such as reading books about software architecture and code languages. But that's not the way they do it in SMG.
It's odd because I spent 20 years pretending to be a salesman for a variety of different manufacturers and wholesalers, so I should be hardened to this stuff. But it's a good thing I was debugging some sample apps at the same time or I reckon I'd have been chewing lumps out of the edge of the desk. Not only was there a weather report by an unbelievably excitable young lady about "increasing cloud across all areas", but even an American Football match between all of the rival vendors with an excruciatingly over-the-top commentary. Though I guess these were only the light-hearted fillings between the hard sell and marketing penetration stuff.
Still, I passed the test and got my course credit, so I should be safe for a few months. And I actually did learn quite a bit about the market that Cloud targets, and its relevance from a business point of view. I guess it will be useful as we document the technical scenarios and provide implementation guidance through our WAG project. I just need to be really careful to avoid any obvious (but oh so tempting) puns around the project name. And just when the World Cup is starting...
Watching a rock music documentary on TV the other day, I heard one of my favorite presenters, Mark Radcliffe, utter the wonderful phrase "Lead guitarists are people who create the soundtrack for our lives". Maybe you have to be of the right generation (it's probably less relevant if your music tastes are limited to folk music, garage, or grunge) but to me it really, if you'll pardon the pun, struck a chord. It requires only the first few bars of a classic rock track, or a snippet of a well-known and much loved guitar solo, to switch my brain into neutral and instantly block any capability for logical thought. Somewhat worrying when I'm trying to write technical guidance while Media Player is tuned to the random music stream exposed by my file server.
I suppose it's partly because I spent my formative years in the period that is now associated with classic rock, that so many of the legends and their music are woven into my consciousness. Yes there are bands around today still creating that magical aura, though even the young kids seem to have a passion that's hard to understand for music that is, in many cases, 30 or even 40 years old. It's odd that rock music has that effect. I can't say I know of many young people who have anything like the same passion for swing, jazz, big band; or for the crooners and songstresses that were the "in thing" of my parents' generation. What is it about classic rock that has radio stations all over the world playing it 24 hours a day, bands where the members should long ago have retired still selling out stadium tours, and endless documentaries and concerts on TV?
And by some odd coincidence, last Sunday I went to see a rock tribute band at a local club - mainly because my wife's cousin plays bass guitar for them. The band, Floydian Slip, perform a range of classic Pink Floyd tracks from Dark Side and The Wall. Unfortunately none of Syd Barrett's earlier work that I remember so well (think "See Emily Play" and "Piper at the Gates of Dawn"). But they are extremely good. The technical accuracy is amazing, and the atmosphere they generate is incredible. Music originally written in 1973, yet some 37 years later is still magical, innovative, relevant, strange, and yet wonderful.
It's hard to think of anything in our industry that you could say the same about after 7 years, never mind 37 years. OK, so I know there are people who still play Space Invaders and Aliens in DOS mode, and there's bound to be somebody somewhere who can't bear to be parted from Windows 3.1. But even XP and Windows 2000, which are barely 10 years old, now somehow seem dated, old fashioned, and unexciting. How is it that a few assorted sound waves generated by amplifying the noise of some pieces of vibrating wire can still create such emotional and magical effect, compared to the way that the full-featured multi-media capability of computer programs seems passé after only a fraction of that time?
Oh how we Brits laughed when the people of the US couldn't seem to decide who was going to be their next president! With their hanging chads, threats of legal action, and people standing in queues for four hours to vote - how could all this happen in a modern, technologically advanced, democratic society? And then we decided to have an election here in Britain...
For a while it seemed like it would be weeks before we found out who actually won, depending on who could be best friends with somebody else. Or until they figured out how many postal votes were rigged. Or what they were going to do about all the thousands of people who couldn't vote because there weren't enough staff in the polling stations. And, yes, it looks like we can still expect some legal action as well. I suppose the only consoling factor is that the whole process only lasted three months rather than a year and a half like it does in the US.
But there is one major advantage - at least for a few weeks while they sort it all out we will be safe from the onslaught of stupid new laws. I suppose it's also one way of saving money and reducing our debt burden. Maybe we'll discover that we can get along a lot better without actually having a Government at all.
And, best of all, it turns out that the leader of the party that experienced the second largest fall in its support is the one who decided who will govern us for the next five years - or until they all fall out with each other and stop being best friends so we can have another go at voting.
I remember, as a kid, reading a Ray Bradbury story about how - in the distant future - elections will be decided by a single person casting one vote. The argument goes that, by then, the whole population will be so closely monitored, analysed, and documented in minute detail on a myriad huge databases that a computer will be able to select the one person who's views exactly mirror the majority of the population. They will be able to just get that chosen person to make the decision. And it seems that, this year, that person is Nick Clegg.
It's lucky they didn't use the same database as one of the major junk mail companies here in England. They manage to include two misspellings in my name, and three mistakes in my address. Though that doesn't seem to stop the post lady from shoving the constant stream of useless advertising through my letter box. But it would have been interesting to see the outcome when some poor guy called Dirk Clark in Cleckheaton answered the phone, and the Queen asked him who he wanted to be prime minister this time.
Mind you, I liked the comment in a letter to the newspaper that said "I just heard that we can anticipate a hung parliament. While I can understand that this is what they deserve after the expenses scandal, surely a good smacking would be a better punishment. Hanging seems a rather extreme option..."
Some weeks ago, I rambled on for a while about making a use case for scenarios. It came about through an experience working on a project where a specific set of features of the software were so complex and unintuitive when you randomly played with them that it seemed almost impossible to provide potential users with any useful guidance on what they were actually there for. I can now reveal that the software in question was the new configuration tool for version 5.0 of Enterprise Library.
I have to grudgingly admit that the new configuration tools are extremely good. Yes, I was doubtful when I saw early versions, but now they've tidied them up and made them do useful things, I really do like them. Even if they are almost impossible to successfully "screenshot" for documentation purposes due to the vast amount of horizontal screen width they absorb. Maybe we'll be OK when they invent books with pages that scroll sideways (or everyone starts using e-readers).
The bits that we (the doc and test teams) struggled with are the advanced configuration options that allow you to generate and consume configuration settings other than all in a single Web.config or App.config file. For some time, because it uses pluggable configuration source providers, Enterprise Library has supported configuration from a database (using a separate sample provider) and configuration that honors Group Policy settings. It's also been possible in the past to generate different run time configurations for different deployment environments, which is useful when the requirements for dev, test, and production systems differ.
However, in the new version you can use shared and inherited configuration settings. The problem was that the features to enable this were called "hierarchical configuration", "redirected sections", and "rules for configuration merge". We all believed that they only made sense to the developer who created them, and were - to say the least - surprised when even he admitted that he was struggling to identify the scenarios for their use. It's no wonder that we doc and test people were breeding whole new migraines every week.
What we had ended up with in the docs up to this point was accurate documentation of each feature, together with detailed instructions of how to do it and examples of the resulting XML configuration content. But there was no way you could decide which of the multiple options you needed in order to perform some specific and obvious task, and you ended up being sidetracked by details of how they worked - basically because, by simply playing with them, that's all you could figure out.
And, of course, the usual documentation nightmare occurs in this situation. As each technical reviewer tries to make sense of it, they add a plethora of comments and suggestions, complete with notes about "things you should tell users" and "important points when using the feature". The result is, not unexpectedly, a guidance document that is basically just a series of notes interspersed with code samples as you try to satisfy all of the requests and feedback. By the time you are done, the content generally makes even less sense, and is even more unusable. All because you didn't (or couldn't) identify at the beginning exactly what the user would want to do.
But finally, after a long and productive teleconference and consultation with our product manager, we nailed down the scenarios for all this. And, when you see them, it all instantly makes sense:
So, tying each feature to a scenario was the missing link. It meant that I could present a list of "What do you want to do?" options, together with an explanatory schematic for each, and then detail the steps for each scenario separately. And, as most of this was already written, the task was not as time consuming as it had seemed at first. It's amazing what a difference it makes writing guidance for software when you understand what it's supposed to do, rather than having to discover what it does and then try and figure out why it does it...
And if you decide to play with the software yourself, I'd be really happy to hear if you agree that we finally did nail it. You can get it all from here.