My experience with runbooks has been:

- I am on a team that oversees a bunch of stuff, some of which I am very hands-on with and comfortable with, and some of which I am vaguely aware exists, but rarely touch

- X, a member of the latter category, breaks

- Everyone who actually knows about X is on vacation/dead/in a meeting

- Fortunately, there is a document that explains what to do in this situation

- It is somehow both obsolete and wrong, a true miracle of bad info

So that is the problem this is trying to solve.

Having discussed this with the creator some[1], the intent here (as I understand it) is to build something like a cross between Jupyter Notebooks and Ansible Tower: documentation, scripts, and metrics that all live next to each other in a way that makes it easier to know what's wrong, how to fix it, and if the fix worked

[1]Disclosure: I help mod the atuin Discord

If the fix/solution would be easily describable and automate-able, it wouldn't/shouldn't be a problem anyway. I don't see how this solves anything.

It shouldn't but often still is... and maybe a runbook like this is easier to handle than a script with possibly 1000 lines and not a single comment. Of course, in your ideal world maybe nothing of this applies and you never have any incidents ;)

> It is somehow both obsolete and wrong, a true miracle of bad info

How does Atuin solve that problem? It seems to me that inaccurate and obsolete information can be in an Atuin document as easily as in a text document, wiki, etc., but possibly I'm not seeing something?

I'm just a community mod, not a dev on the project, so take this with a grain of salt:

I believe the intent is that you get bidirectional selective sync between your terminal and the docs, so that if what's in the docs is out of date or wrong, then whatever you did to actually fix things can be synced back to the docs to reduce the friction of keeping the docs updated.

Thanks for this explanation. This makes sense.

To me, it seems like it's because the thing you're fixing is actually the "runbook" that's being run. Instead of separating the documentation from the code, they're married together so it's easier to keep them in sync because you aren't having to remind yourself to go edit this secondary location when you make a quick change.

I'm cautiously curious about something like this, although I haven't tried it personally.

Yes, seems like right now pendulum is going in other way and separation is no longer in fashion and now fashionable thing is to have everything in one place.

The idea seems interesting to me just cause I do not really like terminals and having something more visually appealing and with better history and comments is an improvement though I am also not sure if Atuin is best way to achieve all of that.

Ok I think I see where this is coming from. I actually think seeing you description that it might even be a benefit to none technical people with no knowledge of what's going on. They can follow instructions and easily execute the relevant code what with it all sitting together.

However I don't see how it solves the obsolete or wrong documentation thing. You still have to make sure the runbook is correct, if it's not you've got the exact same problem.

Having a centralised place for all your scripts is an advantage with inline docs. But then this is a local desktop version...

Seems like this is literate programming for shell scripts.

Thus “Runbooks That Run.”

I was going to talk about using powershell but just for the rust I also really like Nushell. I personally would take either one over this...

Well, what is the purpose of deployments being built in ansible or deployer or whatever tooling as a general rule? And then packaging, say, extra python scripts to perform common tasks then dumping it all in a git repo?

Some people just like a particular workflow or tooling flow and build it really. Maybe it works for enough people to have a viable market, maybe not.

I am just using a PHP deployment process for no reason other than feeling like it for personal projects and it handles 60% of the work without me needing to do anything. But any runbooks for it are tasks built into the tool and in the same git repo for the entire server deployment. I'm not gonna put it in some random place or a shell script that I need to remember separate commands for.

Code, for programmers, is inherently self-documenting if you keep a simple functional style without any complexity with comments on the occasional section that isn't just "Create a MySQL user, roll the MySQL user's password, update the related services with the new password/user combination, remove the old user that the fired employee has credentials to on the off chance we failed to block them at the VPN" kind of stuff.