While the idea of it is nice, I've never actually used it more than once or twice. Instead I write runbooks in Confluence, and that evolves over time.
Confluence is fantastic for runbooks. It's accessible to all kinds of users, you don't have to grant access to them, you get comments, people can edit on the fly without a review, the content is versioned, and most importantly, includes mixed media. My runbooks are often a mix of video clips, screenshots, text, and links to other pages.
In order to automate the runbooks, I do a couple things:
1) I write little scriptlets and either drop them into the runbook as one-liners, or commit them to a `./bin/` directory in a repo with some basic documentation. 1a) If I write a script, usually I make it so it takes some arguments and produces output, so that it can be modified later in a backwards-compatible way, and so it can be composed-with. Every time I do this, I'm making automation easier later on.
2) I have a deployment wrapper `deploy.sh`, and a CI/CD job that calls the wrapper. If I make my scriptlets call-able from `deploy.sh`, then my scriptlets get to take advantage of all the environment set-up my CI/CD job did, so I don't have to do any more work to get the CI/CD system to call my scriptlet. And since my CI/CD job can take parameters and pass them onto `deploy.sh`, and `deploy.sh` can pass arguments to my scriptlet, and my scriptlet can take arguments, I can now re-use the one CI/CD job I made, to call my scriptlet, from any CI/CD pipeline, or from a one-time API call to the CI/CD provider with parameters.
3) I have a Slack bot that'll take commands from Slack and call the CI/CD job with parameters. Now I'm enabling chat users to call automation from Slack, reusing the CI/CD, reusing the deploy.sh, reusing my scriptlets, enabling users to call automation from their chat window.
4) I modify the Slack bot to allow users to edit cron jobs (really just scheduled CI/CD jobs) to run tasks on a regular basis. Now they can either use pre-written scripts, or write their own, and schedule them to run regularly.
Now, my day job has quite a few different responsibilities (as all Sysadmi-cough I mean "DevOps Engineers"- tend to have), so I don't have time to build all this in one go at each job I work at. I build the whole thing slowly over time. As each new feature is available, I release it for use: first the Confluence runbooks, then the scriptlets, then the CI/CD jobs, then the Slack bot. It takes about two years for all of it to be ready. But once it is, it's amazing how much productivity a whole team of people gets out of it.
If I was allowed to do all this automation at once, we'd reap the benefits much sooner. But people who have never seen the rewards of automation never prioritize it.
Confluence is fantastic for runbooks. It's accessible to all kinds of users, you don't have to grant access to them, you get comments, people can edit on the fly without a review, the content is versioned, and most importantly, includes mixed media. My runbooks are often a mix of video clips, screenshots, text, and links to other pages.
In order to automate the runbooks, I do a couple things:
1) I write little scriptlets and either drop them into the runbook as one-liners, or commit them to a `./bin/` directory in a repo with some basic documentation. 1a) If I write a script, usually I make it so it takes some arguments and produces output, so that it can be modified later in a backwards-compatible way, and so it can be composed-with. Every time I do this, I'm making automation easier later on.
2) I have a deployment wrapper `deploy.sh`, and a CI/CD job that calls the wrapper. If I make my scriptlets call-able from `deploy.sh`, then my scriptlets get to take advantage of all the environment set-up my CI/CD job did, so I don't have to do any more work to get the CI/CD system to call my scriptlet. And since my CI/CD job can take parameters and pass them onto `deploy.sh`, and `deploy.sh` can pass arguments to my scriptlet, and my scriptlet can take arguments, I can now re-use the one CI/CD job I made, to call my scriptlet, from any CI/CD pipeline, or from a one-time API call to the CI/CD provider with parameters.
3) I have a Slack bot that'll take commands from Slack and call the CI/CD job with parameters. Now I'm enabling chat users to call automation from Slack, reusing the CI/CD, reusing the deploy.sh, reusing my scriptlets, enabling users to call automation from their chat window.
4) I modify the Slack bot to allow users to edit cron jobs (really just scheduled CI/CD jobs) to run tasks on a regular basis. Now they can either use pre-written scripts, or write their own, and schedule them to run regularly.
Now, my day job has quite a few different responsibilities (as all Sysadmi-cough I mean "DevOps Engineers"- tend to have), so I don't have time to build all this in one go at each job I work at. I build the whole thing slowly over time. As each new feature is available, I release it for use: first the Confluence runbooks, then the scriptlets, then the CI/CD jobs, then the Slack bot. It takes about two years for all of it to be ready. But once it is, it's amazing how much productivity a whole team of people gets out of it.
If I was allowed to do all this automation at once, we'd reap the benefits much sooner. But people who have never seen the rewards of automation never prioritize it.