Robin Sloan’s post about “home-cooked” code has been making the rounds, and for good reason. It’s about highly personalized programs; when you build something purely for yourself or a small audience, it’s more like home cooking than industrial production. I really love the analogy, and it’s inspired me to write about one of my own “home-cooked” tools:
I spend a lot of my day in a terminal, and command line interfaces have notoriously poor discoverability. It’s easy to remember the handful of commands+flags you use on a regular basis; it’s much harder to remember the ones you only use a couple times a year. So, like many people, I used to spend a lot of time digging through man pages when 1) I know what I want to accomplish 2) I can’t remember the exact CLI syntax to make it happen.
Unfortunately, man pages usually aren’t designed for this. The average man page is more like a lengthy novel than Cliff’s Notes; it’s thorough+exhaustive documentation when I just want a quick reference.
There are a few excellent projects that provide succinct documentation for *nix commands:
cht.sh are my favourites. But they don’t provide good facilities for adding personalized documentation of my own; that’s where
wat comes in.
What Wat Does
wat started out as a simple wrapper around
cht.sh. The two provide similar content, but they do so in different ways;
tldr is installed locally,
cht.sh is usually accessed through a dead-simple web interface:
curl cht.sh/command. The first iteration of
wat was just a simple fish function that would call
tldr if it’s installed, and otherwise fall back on
wat is written in Python and it’s a tiny bit more sophisticated: it also displays custom Markdown notes which are synced across all my machines using Git.
Say I want to get some information about a video file, but I can’t remember the exact
ffprobe syntax. I just type
wat ffprobe in my terminal:
This returns a handy
cht.sh summary and it renders the contents of
~/notes/ffprobe.md if it exists. In this case, it looks like I got annoyed enough by
ffprobe to write down a note for the
I’ve been maintaining command line notes for a long time, in various tools that just happened to be at hand: OneNote, Notes.app, Markdown in a repo… but
wat lets me organize that information better, and view it inline with excellent community-provided documentation.
How Wat Works
wat is embarrassingly simple; it’s a single-file Python script gluing together more sophisticated tools.
wat and its notes across all of my computers with a Git repo and the excellent Dotbot tool. This is just piggybacking on my existing approach for dotfiles. The note files are rendered from Markdown using mdcat, and tldr pages are cached/accessed using the excellent tealdeer client. I’m also using the lovely
sh module, which greatly reduces the friction of “shelling out” in Python.
wat solves CLI documentation for me. I have an unusually strong preference for Markdown, and I wanted something that would integrate nicely with my existing dotfile syncing. That’s all I really need. It might not work for everyone, and that’s totally okay! I’m
cooking coding for an audience of one.