I have a love-hate relationship with runbooks. I see them as tech debt for things you haven’t yet automated or made clear enough. If someone needs to go read a doc to understand what they need to do, you’re already behind.

I can't find it now but I remember reading a post on HN with the suggestion to make all your runbooks shell scripts, even if all they start out as a series of prompts walking the user through the checklist of manual tasks.

This way you can incrementally automate various pieces of it so that gradually the user is doing less and less, but there's continuity on their end: run the script and do whatever it says to do next.

I'm guessing this is "Do-nothing scripting: The key to gradual automation" https://news.ycombinator.com/item?id=29083367

Although the example uses Python, rather than shell.

That’s it, thank you!

I love this idea! The automate the easy bits (or the steps that are the biggest pain/time suck) until the whole thing is completed.

A tool like Jupyter Notebooks would be great for this - comments & code can be placed into a single document. I'm working on a project called unSkript (https://unskript.com) that is built on this idea.