When you do the same thing over and over, the best thing to do is automate it. We all know that.
However there are simply some things you cannot automate. As horrible as that is to say in today’s world, you cannot automate things like “Proofread content for errors.” Why? Well a computer only knows to look for what you tell it to look for. And if you habitually typo homophones, you’re in for a long day.
That’s why we have things like checklists. Do X, check Y, etc etc. They’re there to ensure when we run the automated steps, we do everything properly.
I spent the first half of April generating Pre-Flight Checklists for a lot of things. How to upgrade things at DreamHost, how to update things at WordPress.org, how to migrate from X to Y, and so on and so forth. The sad thing is that I’ve had to do all these for long standing processes which exist mostly in someone’s head.
Here are some tips to how I do it.
Write Your Checklist As You Do It
If it’s a process you know, have a document open (or a piece of paper) and write as you go, enumerating every single step. Be pedantic.
On Your Computer:
- Generate list of X
- Go to Y and click BUTTON
- Copy list to DOC
- Run TOOL to output new file
- Add new file to repository
- $ git commit -a FILENAME
- $ git push
On Remote Server:
- SSH to 123.45.67.89 as your ID
- Go to folder BAR
- cd /home/blah/foo/bar
- Dryrun sync command
- sync bar baz –dry-run
You get the idea. Like I said, be specific and get every single thing you do. Don’t worry about getting everything perfect. This is about getting all the information.
Walk Through Your Checklist
Once you have it up, walk through it and do everything (except the actual code push parts). This will show you how you can clean it up and what needs to be explained better. I find it helpful to ask myself “If I was new, would I know what ‘the remote server’ is?” If the answer is no (which it often is), I become more pedantic and specify what server to connect to and exactly how.
For example instead of “Connect to Servername” I’ll put in this:
- Connect to production server
ssh servername
— use your ID and password
Using the different font helps me to know it’s a command and not directions. Any time you feel something is vague, explain it. Put in examples of output. Don’t be afraid to break the ‘flow’ of a checklist to ensure clarity.
Ask Someone Who Knows to Proof
If this is a process someone else has done, grab them and have them skim it for anything obviously wrong. Often I’m writing and refining a checklist for something I don’t actually do, but I watch regularly. With that mindset, I’m able to write from a place where I know enough to know what has to be clear to someone new. A place of no assumptions.
That person should question your claims. if you say “Check X” and they come back and ask you “Why are you doing X in step 15? You do the work in step 4. Why not do them together?” That’s a good thing! You want to be clear, but if there’s work that’s duplicated, you can save yourself and the future-you time. Also that person is going to be the one who says “We should explain why we do this…” They’re going to teach you more about the process.
Ask Someone Who Doesn’t Know to Proof
This is harder. You need someone who knows ‘enough’ that you’re not explaining what SSH is, but doesn’t automatically make assumption. This may be why I end up on checklists a lot. I pestered the hell out of my coworker, Mike, and asked him to explain things in broad terms and then nitty gritty. I asked him to walk me through the steps, then I wrote them down and turned around to someone else and asked “Does this make sense?”
Why? Because Mike was too close to it to see the forest for the trees, which is a good thing! He knows it all! I was fairly close to it, enough to possibly get in over my head. By grabbing a total novice, we had the trifecta of brilliance. That third person asked “What is this?” and noted multiple things that might be wrong.
Release and Iterate
You’re going to miss things, so every time you do the process, have the red pen ready.