The Humble Scrapbook: Keeping a Running Log of Your Intermittent Tasks
There is a peculiar category of chore in the life of any system: the intermittent task. It’s not a daily cron job, humming along with such regularity you forget its pulse. Nor is it a full-blown emergency, setting off alarms and demanding a war room. It’s the work you do every few months, or maybe only when a specific, quiet warning appears. You might prune old log files, rotate a forgotten credential, or run a sanity check on a legacy data store. The problem is, by the time you need to do it again, you’ve forgotten the precise incantation.
You find yourself staring at a shell history that only goes back a week, or sifting through a project’s documentation that explains the what but not the how-you-actually-did-it-last-time. Was it ./manage.py cleanup --force-orphans or --purge-orphans? Did you need to set that special environment variable first? The knowledge is trapped in the past, and rebuilding it from scratch each time is a subtle drain on focus and a potential source of error.
The technique I’ve adopted to combat this is embarrassingly simple. I call it the operations scrapbook. It’s a single, append-only text file, named something like ops_log.md, kept in a well-known directory, perhaps right in the root of the project or in a personal notes repository. Its rules are simple: every time you perform one of these non-routine tasks, you make a new entry. You date it, write a brief sentence about the context, and then paste the exact commands you ran, along with any relevant output or observations.
The Anatomy of an Entry
An entry doesn’t need to be prose; it’s a quick sketch for your future self. It might look like this:
=== 2024-10-27 - Pruning pre-migration user uploads ===
Context: Noticing /data/uploads getting full. Policy is to remove files older than 3 years if the associated user account is inactive.
Commands:
$ cd /srv/app/current
$ RAILS_ENV=production bundle exec rake storage:prune_uploads[1095]
Output:
Pruned 1,204 files, freeing 4.7GB. No errors.
Note: The rake task handles S3 lifecycle policies too, so no separate CLI call needed.
The magic is in the concrete specifics. It’s not a list of possible commands from a help menu; it’s the exact sequence you used that worked. It captures the working directory, the environment variables, the slightly odd syntax of a rake task with arguments. The ‘Note’ line is gold—it captures a realization or a piece of context that isn’t in the command itself, saving you from re-deriving it next time.
This scrapbook is the antithesis of formal documentation. It’s messy, chronological, and utterly practical. It doesn’t try to be comprehensive; it only records what you actually did. Over time, it becomes a narrative of your system’s care and feeding. When a task becomes frequent enough that its scrapbook entries are clustered together, that’s the signal to maybe script it or formalize it. Until then, the scrapbook is the lowest-friction way to build a bridge of context between the you of today and the you of six months from now, who will be grateful for the small, honest record left behind.
Notes & further reading
A few pages I came back to while writing this: