Documentary Evidence

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.

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:

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 put it on a computer in 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...