Put Your Runbook in Your README

If the README is among the highest-impact, most discoverable places to document workflows, why don't we put our scripts there? The typical marquee reason is that READMEs are non-executable: they're prose, not code. This makes them suffer in the critical "specificity" criterion for runbook technology. Enter xc, the task runner for your README that works seamlessly with your CI, shell, and editor.

xc is a task runner similar to Make or npm run, that aims to be more discoverable and approachable

To use it, take all the commands you run to build, debug, test & deploy and document them in your README as code blocks, each under a descriptive header, like "Build". Then run xc build and it'll find that header in your docs and run the code block there.

Crucially, put your CI steps in your README and run them on each merge or release. Quality of life here is good: it supports dependencies between blocks, script arguments and plenty more.

You can also include usage instructions, caveats, deprecation notices, links, and other context right there next to the task's script. And it'll actually look nice, since you have all the info presentation tools normally available in READMEs at your disposal, instead of just spartan code comments.