Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    Documentary Evidence

    • 0 Comments

    You'd think that, with only a couple of different letters, "documentary" and "documentation" were reasonably similar things. But it seems that the makers of TV documentaries have different ideas. It's all a bit like the music of my generation - prog rock. There's plenty of hidden (and often indecipherable) underlying meaning, but it's exposed only though a pompous and often patronizing soundtrack.

    In fact, sometimes you have to wonder if the makers actually started with just a pile of random video clips and glued them together to illustrate some theme they decided afterwards has a remote semblance to the content. And, of course, no self-respecting documentary will be less than an hour long so they need to pad it out with dramatic footage of nothing in particular, and layer it with passages of overbearing music that makes it almost impossible to hear what the presenter is saying. Try any documentary about astronomy for a typical illustration of these factors.

    A talking head

    So I can't help wondering how our documentation would turn out if we followed the same principles. OK, we do the "talking heads" bit in our guides these days to provide additional context and help readers navigate the content. This is a typical example from our series of Windows Azure guides.

    What we try to avoid is the flagrant glossing over of facts along the way. You know the kind of thing: "Scientists have determined that some distant galaxies are clustered around a huge black hole that is absorbing all of the heavy metals and converting them into new ultra-dense planets." How do they know? Did someone just take a wild guess? Have they got photos from the Hubble space telescope? Where's the proof?

    We also try to provide practical solutions. I watched a science program the other day that explained the effect of numerical powers by saying that if you folded a piece of paper in half 42 times it would reach the moon. But they failed to demonstrate or test their hypothesis, and I reckon they got the answer wrong anyway - by my calculation it would only reach 2/3 of the way unless you used thick paper. If we'd been doing this, our dev guys would have written some sample code to test it (welcome to patterns & origami).

    Another annoying factor that's increasingly encountered with TV documentaries, a complaint not just from me but one that was actually acknowledged by the BBC, is the fact that the background music and sound effects noises are often louder than the commentary. OK, so I'm a bit deaf on a good day, but surely the words are the main factor in a documentary. If our documentation followed a similar approach you'd probably see something like this:

    Words you can hardly see


    And then there's the fact that you've already been watching for ten minutes when the opening titles suddenly appear and you realize that everything you've seen so far is just a preview of the good bits, and you are going to have to watch them all over again later. Or how, every time they come back from an ad break, they have to tell you the story again from the beginning in case you were so enthralled by the commercials that you forgot what you were watching. 

    However, the most annoying feature of current documentaries is the condescending and inane suggestion that we don't know what common things look like. Whenever the presenter mentions the phrase "the big bang" it's now mandatory to show a ten second clip of an explosion, just in case we can't quite remember what one looks or sounds like. Or every occurrence of the words "string theory" has to be accompanied by ethereal tinkling noises and something that resembles the Matrix screensaver. I've started calling this "stupidity pictures", or the "nursery book" effect. Perhaps we could try it out:

    When deploying code Some code put it on a computer A computer in a datacenter A datacenter.

    I'm reasonably convinced that it wouldn't add much to our documentation, and might even be a little annoying, though I suppose we can give it a try if there's sufficient demand...

  • Writing ... or Just Practicing?

    Optimistic Euphemisms

    • 0 Comments

    Buried in a recent issue of my newspaper the other day, squashed into a corner between an advert for luxury cruise holidays and a delightful close-up photo of some newly-discovered bacterium, was a short item about a recall by a major UK-based motor manufacturer. It said that in some circumstances the cruise control of some of its diesel models, if engaged, cannot be disengaged in the "normal manner".

    The article went on to explain the company had contacted drivers and warned them that "in some circumstances the cruise control may not respond to the normal inputs". I looked in the handbook for my car and the "normal inputs" for turning off the cruise control are the switch on the steering column and hitting the brakes in panic. In most cases, I suspect that the latter of these is the most useful one, but it would certainly be nice to know that at least one of them worked.

    However there's no need for concern because, as the company explained, turning the ignition off cancels the cruise control function. Of course, it also turns off the power assistance to both braking and steering functions. Try it sometime (preferably at no more than five miles per hour) - you need arms like a gorilla and feet like an elephant to make them work.

    So it seems further scrutiny of the short article suggests that the sequence of events following the solution may be somewhat more complex than originally suggested in the rather optimistic euphemisms provided. As a regular reader you will, of course, realize that here at p&p we are resolutely scenario-focused, and so our guidance on recommended actions would be much more useful. We'd say something like this:

    Scenario: You are traveling on a main road at 70 miles per hour and encounter a roundabout.
    Problem: You anticipate that entering the roundabout at 70 miles per hour may not be conducive with safe driving techniques, may impact the stability of the vehicle, and the centrifugal force generated is likely to exceed the tyres' capacity for grip on the road surface.
    Actions: Apply force to the brake pedal. Panic when nothing happens (optional). Turn off the cruise control using the switch on the steering column. Panic when nothing happens (less optional).
    Forces: The engine will continue to run at speed even when you apply normal inputs to the cruise control function, impacting your ability to reduce speed. To counter this, consider turning off the ignition.
    Liabilities: Turning off the ignition will severely reduce the efficiency and throughput of steering and braking functions.
    Solution: You are going to die.

    Surely that's a lot more informative and useful? And an obvious justification for our scenario-based approach to user guidance. Maybe they'll give us the job of writing the handbook for their next new model...

  • Writing ... or Just Practicing?

    Happy 60th Birthday, LEO

    • 0 Comments

    According to folklore, in 1943 IBM's chairman Thomas J. Watson said that the world would only ever need five computers. Whether he actually did say this is doubtful, but according to various archives this was the general opinion around that time. And it prompts the question: how many computers actually existed then?

    You'd expect, obviously, that it was less than five and that IBM was hoping to sell the other four to some unsuspecting punters who happened to own very large air-conditioned rooms and a power station. But, of course, the first true electronic computers weren't built until a few years later; Colossus at Bletchley Park in England (the Station X computer for decoding encrypted military communications) in 1944, and ENIAC in Pennsylvania USA (used by the US Military for calculating artillery firing tables) in 1946.

    Less well known is the first true business computer. Amazingly, IBM's 700 model was narrowly beaten to the title by a group of accountants and electronic engineers hired by the boss of a gentile English tea-shop. Together they created Lyons Electronic Office (LEO), which started work calculating the cost of bread deliveries in late 1951 and then moved on to do the payroll and more.

    Much is made of the fact that it had an execution speed of only a twenty thousandth of an iPad, power consumption was 30,000 watts, and it took up about 5,000 square feet of floor space (see Lexikon's History of Computing). Mind you, if an article I read last week is correct two thirds of people who have an iPad use it less than twice a week; and probably don't achieve anything as useful as counting loaves or calculating the optimum ratio of milk and sugar in a cup of tea.

    Meanwhile, according to his blog, Oracle's Greg Papadopoulos reckons there actually will be only five computers in the whole world soon. I assume he means that the rest will be just web browsers and smart applications on phones. And probably all written in HTML 5 and JavaScript.

    Hmmm, so it's 1997 and "Dynamic HTML" all over again...

  • Writing ... or Just Practicing?

    How Much Is It Worth?

    • 0 Comments

    I discovered this week that I was severely overcharged when I bought a new TV from our local branch of Comet (a national electrical retailer) some months back. According to a back of an envelope calculation, my TV was actually worth somewhere around one five thousandth of a penny.

    This must be true because an investment company just bought the entire Comet chain of more than 400 stores and all of their stock for just one pound. Though they had to pay a pound extra for the sister company that does the extended guarantees. I wonder if the transfer was made through some complex international banking transaction with four-inch-thick wads of sales contracts, or if the boss of the investment company just tossed a couple of pound coins across the table and asked for a receipt.

    Meanwhile, you may have read about the debacle a couple of weeks ago at the Ostwall Gallery modern art exhibition in Germany. It seems that a cleaner mistook the dirty stain on the floor under Martin Kippenberger's exhibit "When it Starts Dripping from the Ceiling" as being a dirty stain rather than part of the installation, and helpfully cleaned it up. They're saying it will cost 750,000 pounds to restore. Unfortunately the artist is dead; I hope someone remembers what it looked like.

    So you can buy a whole chain of major retail stores for one pound, yet a dirty puddle costs three quarters of a million pounds. It's no wonder we have a financial crisis. Perhaps they can find a few hundred dirty puddles in Greece, Ireland, Italy, Portugal, and Spain (it shouldn't be hard this time of year) to sell off and balance their books.

    But I suppose the real question is whether there is a relationship between value and cost. I reckon there's more value in a chain of major retail stores than in a weird modern art installation, but I guess that's only my opinion. Maybe I just don't appreciate the artistic merit of a few bits of wood, a plastic tray, and a dirty puddle.

    So how do you measure the value of something that costs nothing? I'm talking, of course, about technical and architectural guidance of the type that our little team strives to produce. And it's not only us; there are thousands of bloggers who give their time, experience, and knowledge for free every day. Yet the total value to application designers and developers is immeasurable.

    Maybe I can get the maintenance people here at Microsoft to nail some odds bits of wood together that we can sell to cover the cost of all the work we do creating our guidance. I seem to remember from my last several visits to campus (usually in February) that there's no shortage of dirty puddles...

Page 1 of 1 (4 items)