Playbooks

Gabriel Weatherhead in “Playbooks Before Automation”:

I’m not a professional engineer but this is something I naturally do for anything that takes more than a half dozen steps. […] While I was toiling away in [Excel] I wrote down what I was doing in a note.

By the time I was done I had repeatable instructions for myself. Clear steps make automation easier and a lot more fun.

(Emphasis mine)

I think Playbook is a really good word to describe this habit.

I tended to use "Checklist" instead, but I do think Playbook encapsulates this concept way better. You are not writing tasks to perform mindlessly, but you are also giving context¹, warnings and the story.²

---

Gabriel is also quoting another excellent article, by Jacob Kaplan-Moss:

Write playbooks before automation […]

We know that writing some code to automate a process isn’t necessarily as easy as we’d like it to be; but we also know that the process is complex, error-prone, messy, or otherwise not great to leave as a manual process.

Playbooks are the middle ground I reach for in these circumstances. When I see a process like this, instead of either doing nothing or just diving in and writing some code, I’ll first write a playbook. A playbook is nothing more than a set of instructions for performing the task – a “recipe” if you will. The key is to be as specific as possible. If this is some sort of task that involves code, you can even include bits of code or shell commands that someone following the playbook could copy and paste.

This gets a few steps closer to the goals of automation – consistency, repeatability, reliability – at a fraction of the effort. And, if you later decide that automation is worth the effort, the playbook serves as a detailed specification for your code.

(Emphasis mine)