There’s a great meme going around about geeks and repetitive tasks. Because geeks will often get annoyed at the effort of doing something manually, they often decide to find a way to automate it – which usually involves a lot more effort than doing it the one time but “geeks win, eventually” because they save time in the long run.
But in the long run we’re all dead. Then what? Who knows how to run your script? What happens when it needs to be maintained? As Jon Udell points out, it’s really not a contest, it’s a process, and non-geeks can play too. Which is why you should also write it down if you’re going to do it more than two times.
OK, “doing it more than two times” is a huge generalization. What I mean more specifically is:
- If you’re in a team environment or doing work that will keep cropping up.
- If you’re doing a task that is non-obvious and/or has a complicated series of steps that is non-obvious to people who are not you.
- If you’re in any kind of critical path that would block shipping or operations if you aren’t there to do the magical things you do.
- If you want to reduce your project or organization’s Bus Factor (help other people become proficient).
- If you want to better understand what you do and how you can improve it.
Then you need to take a step back and document the things that you do on a regular basis, because it will help your teammates and (most likely) even you when you come back to a task that you haven’t done for a long time.
Naturally, I’m thinking of this in terms of a project like CloudStack where documentation is vitally important. The success of a distributed team depends a great deal on good documentation.
An Example
Yesterday I spent the better part of the day doing something that, by rights, should have take 30 to 60 minutes – depending on the whims of the bandwidth gods while copying up docs to the server.
Unfortunately, what I was working on was not well-documented. This isn’t surprising, it’s something we’ve only had to do as a project twice and the first time was the “let’s figure out how to do this” run. I captured some of the documentation during the second run, but not in enough detail and missed one step that wound up setting me back by a big chunk of time.
How this could have been avoided: The second time we did this, as a project, it should have been well documented and put up on the wiki.
Getting it Down
While you’re working, keep a scratch (text) file open at all times. Shell history is nice, but it’s often hard to decipher after the fact, especially if you have a lot of trial and error going on.
When you run a command or do something that works, put it in the file. Even if you do nothing more than make public a list of steps that worked for you, it’s light years ahead of having to start from scratch.
After you’ve done $task, take a few minutes to brush up the list you’ve created and (if necessary) fill in any gaps like the requirements needed to run the commands you’ve used, the files you need, where to get source – whatever. Just think about how you got to the state you were in before Step 1 that may not be obvious to anyone else.
Plain text is absolutely fine, and usually preferred.
Getting it Out
If your project uses a wiki or something like that, now’s a good time to put it in the appropriate place in the wiki. Note that putting documentation in an obvious place is sometimes as important as creating the documentation in the first place. A hidden README file in a disused directory on SVN isn’t much help if your project usually looks to the Web for its docs.
You can, and also should, put it up on a blog. This is not a natural impulse for most hacker types, but more’s the pity that it isn’t. First, you can get feedback that way from people you’ve never even heard of. You may take it with a grain of salt, but you may also learn something you never would have learned any other way from someone who is an expert at what you’re an neophyte at. (Note, this can also serve as a resume addition of sorts that demonstrates to employers that you are capable of putting words on paper, and that you’re constantly learning.)
Finally, assuming you’re doing it with a project or organization: announce your new docs on the appropriate mailing list. This way anyone who has an interest can benefit from your new docs, and you also can enjoy a little peer review. (Note, make a practice of thanking people if you see this happening, as a little encouragement is nice and shows that – yes, someone actually just received the message in a bottle that was just sent out.)
Share Your Brain
If you’re the type of person who’d rather automate a task than repeat it, then you should also think about helping others (and future you) avoid having to repeat learning how to do something you’ve already figured out. The extra time that it takes to document something is no different than the extra time it takes to write a script; it’s saving work in the future by doing a little extra now.
I’ve never quite gotten the hang of Subversion (SVN). Most of the stuff we do on 
It’s taken a lot longer than I had planned, but the 
Linux User Groups (LUGs) were a really important part of Linux’s success in the early days when there was little corporate support for Linux, and things were a lot more primitive. Have problems getting that new video card to work? Ask the folks at the LUG, odds are somebody’s already figured it out. Run into a problem getting the latest Red Hat release to work with your SCSI card? Ask the LUG.