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.
...
