Random Disconnected Diatribes of a p&p Documentation Engineer
Last week I mused about how some instruction manuals ("guidance documents" in p&p-speak) are wonderfully accurate, really useful, and may even have helpful pictures. I guess the quality of the documentation depends to some extent on how much you pay for the product; and, hopefully, how dangerous it can be if you get using it wrong. But, in terms of "can be dangerous", a colleague recently reported that she had an example of just the opposite.
She's had the builders in for what seems like the past year building a "deck" that measures about 800 square something-or-others. I asked if she was building a scale model of the Titanic, but it turns out that it's a garden feature type deck that goes twice round the house, and probably fills hers and next door's garden as well. Anyway, she decided to top it off by purchasing a nice big gas barbeque so she can throw a deck-warming party. However, it seems she was somewhat perturbed to discover that the instructions are totally incomprehensible, except for the parts that are completely wrong. As she said, "A bit worrying for something that's supposed to reach 800 degrees".
But best of all, according to the documentation, it comes "complete with four catsers". She said she'd spent ages sorting through the box and all the packaging, but could find nothing with fur, sharp claws, and whiskers. So I decided to do some research for her on the Internet (which is, of course, always completely accurate) and I am pleased to report that I have the answer. According to a definitive resource, a "catser" is the opposite of a "mouser". It's a large, and usually angry, black rat that chases and eats cats. I’m pleased to say that I got an invite to the deck-warming party, but I think I'll maybe give the first one a miss, or pretend I'm vegetarian, just in case she actually found the catsers afterwards.
Anyway, talking about things that get hot, why is it that stuff seems to get hotter as it gets older? OK, so I guess this happens with lots of things (I'm no spring chicken and I do tend to get very warm after ten minutes brisk exercise, such as typing fast). But where I'm coming from here is with an ADSL modem. The previous two I had were installed by the phone company and had integral mains transformers, so you’d expect them to get a bit hot. Especially as we get lots more volts for our money here in England than they do in many other countries.
These modems seemed to have a working life of about a year, and when the second one failed I couldn't face another fight with the phone company so I decided to purchase my own; making sure it had an external mains power pack. For the first couple of years it ran at a nice comfortable "just warm to the touch" temperature. However, suddenly it's started to fail regularly through overheating. Now I have to keep it on one of those laptop cooler things, and have a desk fan roaring away in the server cabinet as well.
If I could get the lid off, I'd vacuum it out like I do with the servers – but how much stuff can there be in an ADSL modem to get gummed up? A friend told me it was probably "thermal runaway" (I did manage to resist telling him that I keep the server cabinet doors locked, so it can't get out). Maybe he's right. At a certain temperature it just loses its self control and transforms into a microwave oven. But the ambient temperature here has not been above about 15 degrees Centigrade. Maybe they sent me a version designed for use in Alaska by mistake. Of course, if I had one designed to work at the kind of ambient temperatures we get here in English summers (it sometimes gets so hot you have to take one of your cardigans off) it would probably freeze up in winter.
Never mind, I've got the perfect solution. I'll swap it with the barbeque. After all, the modem has really good instructions, definitely no catsers, and is just reaching the right temperature now for cooking burgers.
Sometimes you just have to feel sorry for developers. They slave away with their high-powered computers, multiple monitors, and earphones stuffed into their ears; glued to the same chair day after day as they battle with endless lines that basically all say the same thing. With only a hundred or so different keywords they can use, they are forced to try adding some variety to the content by dreaming up exciting names for variables, varying the number of spaces between words, and maybe (in a fit of carefree adventurousness) putting those curly bracket things on the same line as a word!
Just think, if they had the freedom a documentation writer, how interesting their job would be. They could vary the words a bit whenever it got boring, or even use different ones. I mean - as a documentation engineer - you have literally (and literary) almost a million words to choose from (see http://www.languagemonitor.com/GlobalLanguageMonitor.html if you think I'm exaggerating), and you can change these in all kinds of exciting ways. You can vary the tense of words in the text, add different word endings, or just add some extra superfluous ones when the paragraph looks a bit sparse. Best of all, you can invent your own new words in some cases, especially when describing some new product or feature. I managed to get away with "Weblication" in a book many years ago, though a Web search now seems to turn up lots of references to this that aren't mine. And in non-formal writing, you can even use punctuation to make things more interesting in an add-plenty-of-hyphens kind of way, or by appending several exclamation marks!!!
Unfortunately, for developers, code compilers tend to complain when faced with keywords like "print-whatever-you-think-is-best", or "do-something-else-for-the-time-being", and using exclamation marks generally has little impact on operatability (there you go, another new word). Calling a method as "GetCustomerDetailsReallyQuickly!!!" is unlikely to increase application performance; and "whatever" is not really useful as a keyword - even within an "if...else" clause.
It's not even as though developers really can use exciting variable names. Of course, C++ programmers are incapable of inventing variable names anyway, having been conditioned as part of the learning process to just change the initial letter of the class name to lower-case. However, C# and Visual Basic developers are allowed to be more inventive, though variable names such as "notSureWhatThisIsYet", "ifThisIsNullWeveGotAProblem", and "myReallyUsefulStringForUseAllOverThePlace" tend to be frowned on by managers. But at least they can usually get away with leaving rude words in comments that the test team won’t see.
What about made-up stuff? Not something you'd usually associate with documentation engineering, but a recent request I received was for twenty totally fictional news articles about five companies that don't actually exist. The articles were for a forthcoming sample application, so I guess it makes sense, and I did have some fun writing them. Rather like an article I wrote some years ago for a sample sports car Web site that described how they can now breed cows in different colors to get the right shade of leather for the seats. Only this time it was about companies that build railway carriages and office blocks, companies that sell private islands and edible grocery store paper sacks, and companies that make pasta burgers.
Just imagine what would happen if you asked a developer to build twenty fictional applications. I suppose they could just take the week off and then explain that - as they are fictional - you can’t actually run the programs they spent all week creating. More likely, you'd get applications with windows full of incomprehensible and unrecognizable symbols and controls that - being fictional - don't react to even the most frantically clicked mouse or thumped keyboard. Err ... hang on a minute; I reckon I've already used all of those applications...
So, for the documentation engineer, life should be a breeze - a constant stream of exciting new opportunities for inventing words, exercising syntax, punishing punctuation, and stretching the bounds of dictionarial exploitation. Unfortunately, there is bad news. In the days when I used to write books for independent publishers, they forced us to abide by something called the "Chicago Manual of Stuff". As I never read this, I used to depend on the editor to convert my beautifully crafted text into something that sounded like it came out of a sat-nav. Usually I could re-contort it so it was a bit less artificial in the rewrite without anybody noticing, but it was a constant battle.
And now? Faced with producing official Microsoft documentation I've had to concede, and try to dampen my journalistic over-enthusiasm. Now I have not only an electronic "manual of style" that contains what seems to be several thousand pages, but an editor who actually knows it all off by heart! Still, the text usually comes back with a remarkable resemblance to what I originally wrote. Either I'm finally getting the knack of this, or Tina is exceptionally gentle with me...
You know when you go to a car dealer and they say the one particular car you're looking at has "had only one careful lady owner", what they really mean is it's been owned by five boy racers, a bus driver, and a DIY freak who rewired it for a bet. In fact the last car I bought was described as a "demonstrator that the Managing Director uses occasionally". Yet, when the vehicle registration documents arrived a week later, it turned out to have had two previous owners. Luckily for the dealer, they are 350 miles away so I never got round to going back to complain.
Anyway, it was looking like time to change cars again, before I had to pay for new tyres, brakes, and whatever else was due to fall off, and I decided that this time I was going to have a brand new car - one with zero miles on the clock and that still smells like the factory. After visiting what seemed like every local dealer, I finally settled on a nice white and relatively sporty one that meets all the increasingly burdensome emission and fuel consumption regulations of the People's Republic of Europe.
Well, actually the decision was my wife's. She instantly made friends with a rather petite and attractive young lady sales executive, and insisted that I buy a car from her. Now I would have preferred to have dealt with some seasoned guy in a grubby sports jacket, so that we could have a good battle over the price and freebies, but this argument held no sway with my wife. In fact, I was told in no uncertain terms that "I had to let that nice Amy sell me a car..."
So when we met her again a few days later for lunch (part of their superb after-sales service I guess), you can imagine that I was quite surprised to hear that her last job was as a warder in a local men's jail. Of course, as is always the case, it turned out that she and my wife have friends in common. I always say that I reckon my wife knows everybody - we've met people she knows in Las Vegas, Denver, Nice, Munich, and most towns of England - so I guess I shouldn't be surprised.
What's really amazing, however, is the whiz-bang, all-singing, all-dancing gadgetry they put into cars these days. I know that we bought something rather nearer the top of the range than an economy model, but I reckon there's more computing power in there than on my desk. LCD displays, sat-nav, Bluetooth, automatic everything, and only a couple of knobs to twiddle with on the dashboard - one of which seems, after a while, to start the engine.
Most incredible of all, however, is that one of the models I road-tested actually responded to voice commands. I've experimented over the years with software that supposedly lets you talk to your PC, and never had much success. Dictated documents might as well be written in Klingon for all the sense they make afterwards, and every command results in it deleting the document or emailing it to somebody in Australia. Yet, this thing seemed to understand anything and everything you said, even with the radio on, and even at 80 miles per hour. On the odd occasion it didn't, it said very politely "I'm sorry, I didn't understand that, please say it again". Still, they tell me that all the commands are listed in the handbook, which devotes only the first three pages to the useful stuff like where the steering wheel is and what the pedals on the floor do. The other 300 or so pages describe the car's electronic management systems and automatic features.
On the subject of documentation (and I guess where I was going with this), the handbook for my new motor is perfect. Well organized, accurate, comprehensive, and even has useful pictures. I wonder how long before the release date they "code freeze" the car's operating system to let the doc team create the "guidance", and if they use agile development to create the software in the first place. My guess is that they outsource it all, that it runs Microsoft Embedded, and it would be nice to think they get 100% code coverage in testing. Having the whole O/S throw a wobbly at speed on a motorway could be an interesting experience.
Meanwhile, there's the constant nagging doubt that any computer geek will recognize. When will it suddenly go wrong? Do I have to install fixes and patches every month? Will it be compatible with CDs by both the Arctic Monkeys and Wishbone Ash? Where do I look for the reset button? I suppose they just plug the car into an even bigger computer when something does go wrong, and ask it the question of fuel pump pressure, the meaning of sat-nav, and everything. Knowing my luck, the answer will be 42.