Stonewall Jackson and documentation¶

Tags: python

Today it is 150 years ago that Stonewall Jackson died. Not everyone will recognize the name: it is a general from the American civil war. And a good one at that!

Bear with me, I’ll have a programming-related comment to make on documentation :-)

If you know a bit about the second world war, you might have heard about the German general Erwin Rommel. Jackson’s fame was a bit like that. If you had to fight Jackson or Rommel, it didn’t really matter that you had more men and equipment: he’d beat the crap out of you anyway. Once at a time Jackson’s 15000 men ran circles around 60000 opponents and repeatedly beat them. That’s 1:4. And they won.

Both Jackson and Rommel seemed to have a Fingerspitzengefühl. They’d known instinctively when to do or not do something. When to lay in wait and when to strike out despite the odds.

Both also seemed to be one-of-a-kind. I mean it in the sense that they could not teach others to do the same. It was all in their own head. It was all dependent upon them. And at least Jackson didn’t tell anything to his subordinates; he was secretive. When he died, there was no one to take his place and no one who could emulate his expertly handling of his army.

Here’s the link with programming: document your stuff. If it isn’t documented, it doesn’t exist. I updated a small internal tool two days ago and had to figure out which commandline arguments to pass to it because I had not originally documented it! There was a README, but only with server installation instructions; no local test instructions. And it only described one of the two scripts. Needless to say, I’ve now corrected this situation.

I wrote the tool originally and I’m the only one working on it. But after I haven’t touched it for a year I sure need a reasonable README to get myself back on track. So: document! Try to pass on knowledge.

Btw, Stonewall Jackson died because he was shot by friendly troops. I’m not suggesting programmers should be shot for not-documenting their stuff, but a forceful reminder here or there could be useful :-)