Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. – Donald E. Knuth
A lifetime ago I was given the task of understanding and maintaining a 4,000 line program written in c that did some clever stuff related to nanotechnology.
Clearly that sounded like no fun at all and so I spent a lot of time trying to find out how to do a better job – and came across the idea of literate programming.
Literate programming is something that has never taken off, something that is a curiosity, hidden in a dark corner, and ignored.
Unless you’re a certain kind of person, possibly.
Some people are doers – they approach the job with vigour and zest and testosterone and get it done.
If you want a wall knocking down these are the kinds of people you want.
Most of the time, actually, these are the people you want.
Then there are thinkers – people who ponder and wonder and plan – with many ideas about how to get things done but not the kind of people who get their hands dirty.
You probably avoid those kinds of people.
Then there are people in the middle, people who straddle the world of thinking and doing and who find that existing ways of doing things just don’t work for them.
Think about almost anything you spend time on.
There is time spent planning and time spent doing.
There’s always this duality – the thing that emerges and the thing that makes it emerge.
I drew a random number of boxes showing this concept and had no problem filling them with examples.
An interesting example that goes back a long way is the Talmud – the Jewish holy texts – that have what you might think of as a core text accompanied by notes and opinions from Rabbis over the years. You need both to understand the whole.
These days it’s easiest to see how this works when you look at computer programs.
All programs end up being written in a particular language.
Programmers create their code and then add comments to help others understand the flow of the code.
Some very macho programmers believe that comments are unnecessary – they can understand well written code just fine thank you very much.
In such programs you end up with a very big core and very little around it.
Now, Knuth’s discovery was that if he took the trouble to explain what his program did he ended up writing better programs – and so he created an approach called literate programming that tied together the exposition and the program – a little like the Talmud’s commentary and text.
And once you see that it’s better to have the two together than either one on its own you’ll see applications everywhere.
Take managing a project, for example.
You could work out what needs to be done and hand out tasks – give people jobs to do.
Or you could take the trouble to explain why you’re doing this project, what is expected, what the main pitfalls might be – and in general communicate – inform the people working with you.
And then do it again and again – make sure that it’s very clear.
All this takes time and effort, and it’s very tempting to just get on and focus on the tasks and core jobs.
But that’s also how mistakes get made – how things fall between the cracks and you end up with unhappy clients and failed projects.
Maybe trying the two together – taking what Knuth called a literate approach is the right way to go.
Except, that it’s not easy to do. It’s not a quick fix, an easy win.
It asks you to do hard things, like think and write and explain.
Which is why literate programming systems are hardly ever used – it appears that only those who create them use them.
I can see the reality of that.
For example, my interest in Soft Systems Methodology could be expressed as a system to do Literate Management – where we articulate and explain the models that sit behind what we do in practice.
The method I use, however, is customised around my interests – bringing together drawing, programming and management – and it is arguably a literate system that pulls together code and commentary.
But what inevitably happens when you overlap requirements is that the area of possibility decreases.
It’s like climbing mountains.
We all start off on level ground – billions of us are there right at the start.
As you go higher, the number of people that reach each level starts to fall until eventually, you have a few people who make it all the way to the top.
But that doesn’t mean that Literate Management is not something we can try and do more effectively.
If you have kids – it’s the difference between shouting at them and taking the time to talk to them and explain why you need them to do something.
If you manage a person it’s the difference between micromanaging their every move and being a coach and mentor.
When we realise that there is this duality – this layering going on between how to do something and why it needs to be done then we can see that by keeping them together we can get better results from more engaged people.
And the thing is, for some of us, it makes what could be a boring job much more interesting.