Describe the thing. Offer boilerplate, examples, or parameterized executables.
The doc system that uses Notebooks de facto would be awesome. It’s too heavy to add as a layer to a Cloud SaaS like Confluence and offers too many opportunities for escalations as is..
It can confirm with the user: "Execute command (y/N)?"
Fuck cutting and pasting stuff from one terminal into another terminal. That's also focus-intensive.
Then prompt the user to do the manual stuff when it isn't yet a command:
"Look up the e-mail address for foo. Paste it here:"
"Put that shit in 1Password: Are you done (y/N)?"
The alternatives are "do everything scripts" which get lost in dealing with how to automatically manage 1password, or documentation which is just a do nothing script that doesn't lead you through the checklist.
I think jupyter notebooks are better suited to fill this role since you can gradually turn a 100% markdown wiki document into a script and offer one-click execution.
Further, because your human oriented process has now codified your system, changes to the system that's would be beneficial to a software system (i.e. dividing the system into components) are impossible. So incremental scale is achieved by stuffing more into the process, which then gets grafted onto the script monolith in a self protruding cycle.
> The moment those scripts start getting called by production services
Any of them with manual steps just can't, right?
> Further, because your human oriented process has now codified your system, changes to the system that's would be beneficial to a software system (i.e. dividing the system into components) are impossible.
Absolutely nothing stops you from changing these scripts - it's no different from having scripts in a package.json
The alternatives are full automation, which pushes your issues to the max, or zero automation which is an odd point to be in.
Or do you mean by automating one step in a script, you risk someone using that part in a production service?
If you are literally using the kind of scripts used here, they can't be called by a production system though their use can be part of formalized desk procedures.
It is a fairly natural next step (and a not unheard of first step in automation, bypassing these) to instead build something like these scripts but into an actual workflow management system where it can be triggered by either a user or even automatically tied to another system event, can be assigned to an available worker, can have status and artifacts tracked, and can trigger downstream processes.
(Of course, once you have the process in such a system, where the human worker is essentially a component the system calls to complete defined steps—contrary to GPs criticism—what you have is equqivalent to a documented process with the notable different that it is much easier to refactor it to divide work among components, etc., just loke any other software system.)
You're basically arguing against the concept of SOPs. OP blog post is basically just a programmer's version of an SOP.
SOPs are great, until they aren't. So then you change them. This is nothing new or strange.
They are more portable, more universal, fewer dependencies.
Whenever you start to install something just put the commands into a bash’s script as you go and run it at each step.
Want to break it apart? Break apart the script how you like and repeat.
Being able to hand someone a scene for Linux or MacOS is a great way to help others begin too.
1) Capture the process as is
2) make the process pass a giggle test
3) make the process automatable
Concurrent with 3 and 4:
- use the process repeatedly and by as many people as possible
- adapt the process to any misuse seen in the wild
4) automate the process
Everybody will buy into steps 1&2, and most people will come around to 4, but doing step 3 usually will get you more people pushing for and understanding 4
The limitation of your approach I will say is that if you can automate the beginning of a process or the end it’s fine, but if you have two islands in the middle it doesn’t work better than a CLI tool with prompts.
But the giggle test is just something I borrowed from business, which is, “can I say this with a straight face?” Which eliminates a lot more censorious than you would think. Writing something down is one thing, making eye contact with someone while repeating it is a bit harder.
I think I may have poorly described my approach then. It's just the same thing, the choice of sheets or Jira or cli or a combo is only about meeting people where their current process is. A dev setup -> cli. A business process between trams -> Jira if that's the current flow. I'm not getting marketing to install my cli tool, and they'd not be the ones doing the manual steps anyway.
The point is just making a process into a series of clearly defined steps that can be manual and can be automated independently.
Your description of what happens alongside 3 and 4 is good, this was really valuable when I've done it. Just like releasing a MVP and finding out key problems with your imagined approach, the issues are usually not what you expect. You also have better test cases and examples.
Massive side benefit when I did this with data was that it also meant a process could be automated 95% of the time, manual 5% without changing the interface anyone worked with. All they saw was the ticket took longer really. That's great when you find absolutely wild stuff in some csv file.
The last time I used it, which is probably eight times now, I freed a team up to attack more entrenched tech debt problems by making them no longer afraid of deploying to run trails instead of waiting to do feature toggles once a release cycle.
Every adult programmer should be able to think of four things they can work on when nobody is telling them what to do for the next little while, and Scrum produces a lot of those. This is just one of the things I do. And when you get close to a quantum of useful improvement you can usually get a story or two on the board.
Fixing your processes is an axe sharpening exercise. If you’d rather be dismissive enough to register a complaint then I feel sorry for the teams you work on.
The approach replaces Confluence instruction pages with semi-interactive walkthroughs (the conscious side).
The other side is test automation: it starts with a big ball of overfitted Xpaths and undocumented steps. Those get re-discovered every time the application changes (the subconscious side).
Hopefully, we reach the summit where we can execute quickly and still know how we got there and why.
In general it's another way of defining interfaces around processes. Those processes may be manually done or automated. But the interface can remain the same - this is quite powerful when it comes to automating steps.
It's the same as you'd do with another system really.
I've used this before with Google sheets being manually filled in -> automated with a script. And with Jira tickets being raised and then automatically picked up and processed. It lets you get started sooner, automated the most annoying parts and you never have to fully do it.
Side benefit of do nothing scripts is that they can remain up to date more often as they can be more likely to be actually used than reading the docs.