10 ms·

Do-nothing scripting: the key to gradual automation

645 points by thameera 7y ago

jsilence 7y ago
Combined with the concept of literate programming this would also help capture the "why"s of the slog, resulting in inline documentation. Jupyter and org-mode for the win!
- ben509 7y ago
  Running such a checklist in Jupyter seems like a very good approach. The big advantage is someone else can pick up from where you started. And reporting is built in as you can save the notebook and review it later. The only thing it lacks is control flow. A good operations script has exit points: if an operation fails, you often want to rollback and abort. Though even there, you can save state in a variable and have a check.
phoe-krk 7y ago
They are do-nothing scripts but it isn't equivalent to say that the scripts do nothing. That is a very important distinction to me. These scripts organize tasks into flows in a way that makes it possible to split work by logical checkpoints. The tasks between these checkpoints are dependent on one another in the overall flow, but have independent implementations that can be delegated to software or done by humans.
kostarelo 7y ago
It seems to me that all you want is to document a manual process. Having them documented in dump scripts is no different than having them documented as a guide in your knowledge base .e.g in Confluence or as product requirements. I can see the usage in an isolated team of a few people that will write these scripts for their own benefit. I am opposed in general with having scarce information around. Better have everything a single place, whether that's a guide on how to provision a user or is how to add a new endpoint to your API or write a new end to end test.
- TuringTest 7y ago
  There is one advantage of this script over an equivalent document: it provides the instructions in the same context that it's being used (the command shell). Unless we have script shells that can universally launch a web document side-by-side from the shell prompt where it needs to be used, having it being displayed from the shell itself step by step will reduce the mental load required to follow the instructions. Also, the benefit of having an already semi-automated process in order to build a script in the future is not negligible.
  - pojzon 7y ago
    I think dual screen solution provides exactly that. Working only on a corporate laptop is very inefficient in this regard.
- lucideer 7y ago
  In addition to the sibling commenters point about providing instructions in context, this approach has another much bigger advantage (mentioned in the article): it informs you of where you are in the process so you don't miss steps. Keeping track of which step you are on while following a long doc is no easy task when some steps needs to be left unattended (and produce scrolling terminal output making viewing the last-run command harder).
- some_furry 7y ago
  Furthermore, some tasks are nonlinear in complexity. Documenting those properly would quickly lead to a "choose your own adventure" type scenario. Most documentation software (i.e. Wikis) do a poor job of encapsulating this. The "do-nothing" scripts might be easier to maintain, but it forces you to use plaintext. I recently started an open source project that might be more helpful for teams (if for no other reason than it uses Markdown): https://faq.dhol.es/@Soatok/public-beta/what-is-faq-off https://faq.dhol.es/@Soatok/public-beta/what-is-faq-off
- iainmerrick 7y ago
  Having them documented in dump scripts is no different than having them documented as a guide in your knowledge base It’s very different, in at least two ways: - If your checklist is on a wiki, people may stop referring to the checklist once they’re familiar with the process. That’s bad if there are important changes. But if the process is “run this script and do what it says”, I think people are much more likely to keep doing that. - When you start automating steps, people using the checklist pick up that automation for free. With a checklist on a wiki, any new automation means the user has to do something differently (eg maybe step 10 is “run this script” instead of “log on to the dev console and disable write access”)
probablyfiction 7y ago
This just seems like checklists with extra steps.
- TuringTest 7y ago
  That you can run from the shell.
- rusticpenn 7y ago
  but this can be gradually automated with less effort than a checklist.
darkerside 7y ago
I love things like this. Mindbendingly simple ideas that rely purely on overturning preconceived notions about what things are "worth" a certain amount of effort. There's a tautological, cart-before-horse paradox in many cases.
sourceless 7y ago
This seems like a surprisingly powerful and should-be-obvious kind of idea... I think I'll start making use of it!
heinrichhartman 7y ago
Very nice idea, Dan! This reminds me of the power of checklists that has been discussed here a few times: Simple but highly effective. It allows for a pretty natural transition: - (Markdown) Manual - Do-nothing-script (printing out the manual in steps) - Partial automation - Full automation
- praptak 7y ago
  The reference article for the power of checklists: https://www.newyorker.com/magazine/2007/12/10/the-checklist https://www.newyorker.com/magazine/2007/12/10/the-checklist Another article, with HN discussion: https://news.ycombinator.com/item?id=20293246 https://news.ycombinator.com/item?id=20293246
crispyporkbites 7y ago
Are there any good slack plugins out there that can do this kind of workflow/ state management?
- NateEag 7y ago
  I don't understand why you would want to introduce Slack to this. What benefits would that give?
  - crispyporkbites 7y ago
    Slack is like the shared OS we never had
    - NateEag 7y ago
      I'm sorry, I still don't understand. The only interpretation of that I'm coming up with is that each step of the process would be kicked off in Slack. Wouldn't that mean people could easily stomp on each other's toes? Wouldn't there also be tons of needless noise as each of us does our workflows? I use Slack daily, but we don't have any automation hooked up in it. I realize some teams drive deploys, alerts, and other stuff through it. That makes sense to me - this does not. Am I missing something?
fredley 7y ago
I can't help looking at this and working out how to build a tool that can generate a Do Nothing script straight from your histfile, making the business of archiving the commands you just executed as easy as possible too...
- jasonjayr 7y ago
  If you're about to do a sequence of commands into a terminal, you can create a transcript with the 'script $filename' command ('script' command is in the util-linux package', according to the man page), and it will capture input/output into the transcript. This would probably make this task easier, since you could see the output data, and how the output data is transformed into arguments into the next command ...
  - vfinn 7y ago
    Came to say this. https://www.youtube.com/watch?v=tweyWNr6X18 https://www.youtube.com/watch?v=tweyWNr6X18
- alexanderdmitri 7y ago
  Reminds me of the time I decided to try kanban to start moving forward on tasks I procrastinate on or have trouble starting. Of course, to make sure it was efficient enough to be helpful it had to be a configurable terminal app I could quickly update and review via cli and abundant io flags/options. It also made sense to write it in Scheme because I had been thinking I wanted to try Lisp earlier that day. Fast-forward three weeks and I find myself hopelessly trying to refactor this strangely ugly-beautiful ascii-art themed effort tracker run by an abomination of labrynthine "functional" source and realize (maybe just finally admit to myself) it was all an excuse to avoid all that shit I'd convinced myself I was going to acheive by kanbanning in the first place. The best part is I regret nothing!
  - jgwil2 7y ago
    Lnk src pls
2T1Qka0rEiPr 7y ago
Nice idea! I'm actually in the process of automating a task bit by bit. Unfortunately it's with the intention of moving it into a CI pipeline, so the "success" there is rather binary, but I will most definitely adopt this process in future.
grecht 7y ago
Great idea! From personal experience I can say that there are some things ops teams never get around to automate, either because there is always something more important to do, or because it would be too expensive to have a developer spend time automating them. This is a simple, quick solution that solves the problem of accidentally skipping a subtask, thus screwing something up and feeling stupid for doing so.
gtf21 7y ago
This is a really great idea, and appealing in its simplicity -- I think we might try to implement this in my company for some of our tasks which are really very manual, but for which automation is a daunting task.
nerdponx 7y ago
I get it, but this script looks a lot like a checklist to me. Seems like a checklist is a good place to start, no? If you want more "interest" during the process, make it a point to refine the documentation for your process (clarify a step here, split one command into two steps). Then you have a very clear spec by the time the process needs to be automated.
- wtetzner 7y ago
  I think the value of using a script as your checklist is that the script can handle some of the book-keeping for you, including making it harder to lose track of where you are.
  - maaaats 7y ago
    It also documents the process, which is often lacking for these one-offs tasks.
- pixelrevision 7y ago
  Each part of a script can be replaced with actual code over time without committing to trying to automate the entire thing. I think it’s a pretty nifty idea that helps avoid putting the whole thing off for later.
victormours 7y ago
This idea is great. You could even argue that these scripts actually do something: they allow storing and updating the state of a process. By having these scripts run in a shell rather than in your head, the current state is stored in a machine, not in an unreliable human brain.
- empath75 7y ago
  also they allow you to gradually script stuff as you figure it out.
  - rakoo 7y ago
    This should be read in conjunction with this other great article about how to gradually automate your process: https://queue.acm.org/detail.cfm?id=3197520 https://queue.acm.org/detail.cfm?id=3197520
    - mturmon 7y ago
      This is a great article, providing even more context for why this stepwise automation is smart.
  - lioeters 7y ago
    That looks to be a big advantage of scripts like this, they allow the gradual automation of processes. I realized that I've written scripts that are "executable checklists", but didn't see it as a design pattern until reading this article. Typically such a script starts out as fully manual (do this, do that next, copy here, paste there..) then I replace steps as actual code, where I can, while some steps remain manual if needed. Great use of such checklist scripts is on-boarding collaborators or new team members in a project. Also, as grandparent comment pointed out, they reduce cognitive load by keeping the state of a process outside the head.
  - jonathanpoulter 7y ago
    this seems like the real magic here. The author states at the start, automating all of the steps of something can be daunting. But this script can incrementally become a do everything script.
js8 7y ago
Seems basically to be a checklist. However, I don't think it's a good idea. Checklists are not bad, but they are to be executed by humans. I think trying to automate an existing human process directly is a mistake. Human processes often have features that only humans can do, such as pattern recognition or adapting to small difference. It's often easier to create a computerized (automated) process from scratch than to try to account for all the edge cases that humans might have to deal with (and do without problems). (The opposite is also true, processes that computers have no issues with can make trouble for humans. For example, humans have imperfect memory. So if the process asks humans to keep track something for extended periods, it can be difficult.)
- iainmerrick 7y ago
  Well, the specific problem it addresses is: 1. We have a tedious manual checklist 2. We’d like it to be fully automated 3. How do we get there from here?? You’re correct to say that if the process had been fully automated from the start it may well have been implemented very differently. But those scripts are hard to write, and basically useless until they’re complete. Often the only practical way to do this stuff is incremental refinement, where each small step adds a little bit of value. The trick is figuring out where to begin. I think the suggestion in this post is a wonderful way to get over that first hurdle.
  - js8 7y ago
    You can do automation incrementally, but it's quite a different mindset to automate computer than to write a checklist for humans. If you try to emulate a person with a checklist, then you will often find it is actually harder to automate, because the steps often rely on human adaptability and common sense.
    - iainmerrick 7y ago
      What other approach do you suggest, then, in the extremely common scenario where you have an existing, tedious yet reliable multi-step manual process, and you’d like to automate it?
timwis 7y ago
What is the value of this over a checklist?
- mattacular 7y ago
  It's explained at the end of the post.
- crispyambulance 7y ago
  I would argue that it _is_ a checklist. The difference is that it's a more gradual entry to automate the task. One could, for example, replace any item with a script/program invocation, while leaving the others untouched. It's an intelligent, piecemeal step towards automation. I would also add that in really critical tasks, one could automate _either_ the item, or it's verification. Sometimes it's easier to check that something is correct than to do it-- or vice-versa.
swiley 7y ago
Is anyone else bothered by how they were handling ssh keys in the example? The whole point of public keys is that the private key never has to leave the box it’s generated on. Once you go sharing them you might as well just use a random passphrase.
- deg4uss3r 7y ago
  Yes, very much so. In addition stop using RSA[0] and use ed25519 with `ssh-keygen -t ed25519` [0]: https://blog.trailofbits.com/2019/07/08/fuck-rsa/ https://blog.trailofbits.com/2019/07/08/fuck-rsa/
  - viraptor 7y ago
    Unless you're using a hardware token via gpg-agent. In that case RSA is the only way most of the time.
    - xemdetia 7y ago
      Yeah hopefully when FIPS 140-3 finishes we'll start seeing hardware tokens that can do elliptic curves.
  - devonkim 7y ago
    Because Jenkins has its own ssh client, that wasn't supported as of last year with elliptic curve based keys and I had to re-launch a bunch of servers in production to downgrade back to RSA or DSA keys because they were basically the only key types that Jenkins supported. Really not sure why Jenkins had to go this far to re-invent a cryptographic wheel (besides the usual "support both Windows and Linux" angle).
- wtetzner 7y ago
  Yeah, at our company things are done in the reverse of that script: the user generates their SSH keys, and there's a process they use to register the public key with the rest of the system.
  - 7y ago
dusted 7y ago
We use this at my place, though in bash, and we call it executable documentation. Stuff like: NAME="$1" # Create directory for the code mkdir "$NAME" # Checkout the source cd $NAME && git something # and so on Sometimes with an echo "You need to read and understand this before just using it"; exit 1 thrown in somewhere for good measure. These files will have no logic, and make very little use of variables. They will also have a .txt filename to ensure that people understand, that first of all, this is a set of instructions for how to do something, which just so happens to be a valid bash script.
- dharmab 7y ago
  We embed similar explanatory docs in Markdown. A short example for dig from our troubleshooting guide: # General form dig @<resolver> <record> dig @1.1.1.1 www.example.com # Omit the resolver to use the system's configured resolvers dig www.example.com # Don't need the full output? dig +short www.example.com
- meowface 7y ago
  This sounds like basically what I use READMEs or supplementary Markdown documentation files for, just in a bash code block in a Markdown file rather than in a bash file.
  - peterbell_nyc 7y ago
    The difference is that every time you do the process, you can consider writing a couple of tests and automating the step.
    - meowface 7y ago
      That's true. I guess I tend to just use those as examples/documentation at the start, and then when I want to automate the process, I do it more in an all-at-once way (with a Python project or something) rather than incremental additions to a bash script. Do-nothing scripting does definitely sound like a technique I should try out. I'm not a huge fan of bash for stuff beyond a list of short commands/steps, though.
Ididntdothis 7y ago
We do a similar thing for tests that are hard to automate. Instead of having the test protocol in a document it’s in a script that prompts the user to do things. The observations are then recorded and stored.
persephonee 7y ago
raw_input is python 2.x. Dont use it.
klmr 7y ago
I know this isn’t the point of the article but the code shown there is the archetypal case where writing classes is an anti-pattern, as argued in “Stop Writing Classes” [1]. All the classes in that code can — should! — be functions. There’s no downside, and it’s less code (and otherwise identical). [1] https://news.ycombinator.com/item?id=3717715 https://news.ycombinator.com/item?id=3717715
- naringas 7y ago
  maybe he was a Java programmer? all joking aside, the reason he's doing classes seems to be an intention towards making a FooStep (and/or a BarStep) which could then maybe handle generic Foo stuff (authentication comes to mind) in the future?
  - epr 7y ago
    "maybe"..."in the future" is the root of much object oriented evil
    - shareIdeas 7y ago
      I don't think there is a correct answer, but I like that a developer has foresight.
      - mattnewton 7y ago
        The problem is you get more information in the future, but all this boilerplate is has been written before that information so the first instinct / seemingly least-resistance thing to do is to fit the new information into the old boilerplate / hierarchy. Lots of people have OO scar tissue from getting weird impedance mismatches on newish OO systems designed this way.
      - sullyj3 7y ago
        Real foresight is understanding the cost of unnecessary technical debt.
      - 7y ago
dradtke 7y ago
Anyone interested in this idea should check out https://github.com/braintree/runbook https://github.com/braintree/runbook
beat 7y ago
I'd go farther... you can have steps that literally "do nothing". They can be comments, or simple echo statements. They're placeholders to remember to write the code for that step later. This is particularly important when you need to deal with integration that isn't necessarily easy - handling auth credential safely, making sure it works in your pipeline, etc. But all this gets back to something I used to say a lot, and the more refined version I say now. I used to say "Have humans do what humans do well; have computers do what computers do well". The key part of that was the idea that computers can't do what humans do. Now, I say "Anything a computer can do well, a human cannot do well". Which includes those pesky twenty step manual processes.
- dkarp 7y ago
  But these steps already do nothing except say echo what should be done. How does that differ from your "literally do nothing" steps?
  - winkeltripel 7y ago
    my hot take is that it differs is that you plan to never automate some of the steps, if they're steps for a human to do. As part of onboarding, you might send out an email introducing this new human. The "description" field of this new human should be written by a person, not scraped from their linkedin or google, and summarized to less than 100 words by a computer.
  - beat 7y ago
    In a truly minimal system, there isn't even a prompt. A code comment is about as minimal as I know how to get. That's just a placeholder to remember to automate a step. When automating a complex manual process, the first thing I do is write comments describing the sequence, and any parameters needed. Parameters in particular can be enlightening, because when manual processes grow organically, naming consistency becomes a source of suffering - humans can just sort of figure out the right thing to type, computers can't intuit these things and they must be made explicit. It's worse when it can't be explicit without updating the process or creating some sort of data store for mapping. This is why naming things is one of the two hard problems in computer science.
abathur 7y ago
This feels like a useful concept. I stumbled into doing roughly the same in my macOS system bootstrap script. I found it from the other side, though--usually only after failing to find a good way to automate a step, or realizing automation would be vastly more complex/fragile than just prompting myself to do something manually at the right time. Probably a more useful concept when it's conscious from the getgo. :)
chousuke 7y ago
In situations where using full-blown configuration management has too much overhead I often do something like this by just copying the commands I run into a script to begin with. It allows me to easily generalize a sequence of actions into a do-nothing template and doubles as documentation. I'm very much against documenting concrete steps in a wiki if it is something that can be scripted. Such documentation becomes something that you must maintain, and faulty documentation is worse than no documentation. I think that wiki documentation should be used to summarize workflows and provide context, but if you're writing step-by-step instructions, often you can just write a script with exactly the same amount of effort.
nmca 7y ago
This is a checklist. Checklists are incredible, and I quite like this version.
lazyant 7y ago
Checklists as Code
X6S1x6Okd1st 7y ago
It's a checklist
nlawalker 7y ago
Suggested upgrade: Have such scripts ask for a unique name/"instance identifier" when run so they can log to simple text files in a well-known directory and potentially pick up where they left off. For when you invariably use these for long-running tasks and have 7 of them in-flight, and your power goes out or Windows forces a reboot.
marshmellman 7y ago
An additional benefit of this approach is that your checklists now get code reviews, git hooks, history, etc. for free. I mention this because I worked at a company where checklists were typically simply added to a wiki and required separate processes for things like peer review.
manas666 7y ago
if you are working at a small shop or startup - then whatever makes you happy, even these classes are OK. if you are working at enterprise - then these processes gotta be implemented according to ITIL in a specialized IT Service Management system - like ServiceNow, which allows building process flows like directed acyclical graphs and automation of necessary steps
- oblio 7y ago
  I'm not sure if this is ironic. I've been numbed by too many years of internet usage, I guess :-)
andrewguenther 7y ago
I have a script in our automation setup called "be-the-change" which takes either markdown or a wiki url as a parameter. It will output the markdown or wiki content, wait for the user to confirm they've completed the steps and then print: Doing manual steps sucks, wouldn't it be great if this was automated for the next person? Be the change you want to see in the world.
orestis 7y ago
I like the checklist nature of this. I approached this problem from another side, which involved a very powerful REPL, but lacked the structure this shows: https://orestis.gr/clojure-unlocking-incremental-automation/ https://orestis.gr/clojure-unlocking-incremental-automation/
pgt 7y ago
This is a good idea. I recently wrote down some ideas about "How to Grow a Program," in a symbolic programming environment: https://github.com/theronic/hoist/ https://github.com/theronic/hoist/ I call it Hoist - from "hoisting up" concrete, hard-coded values into abstract symbols for reuse. It's complete vaporware at this point, just a place to collect my thoughts for a future essay.
- teddyh 7y ago
  See also: In TDD, there are defined steps you go through as you gradually refine your code to actually do more and more things; from returning nothing, to returning one value, to returning a list, etc.
mbar84 7y ago
Interesting idea! I'll wrote some boilerplate that I think is a bit nicer: https://gist.github.com/mbarkhau/60fc4bbe505914369ebd2fec1ab6d21b https://gist.github.com/mbarkhau/60fc4bbe505914369ebd2fec1ab...
AstroJetson 7y ago
Why do I think that writing a script in Expect (https://en.wikipedia.org/wiki/Expect https://en.wikipedia.org/wiki/Expect) would take as long as doing this and then you would be done?
- moonbug 7y ago
  ..because you've never tried using expect in anger?
  - AstroJetson 7y ago
    Nope, I like Expect, it's my friend and I'm able to make scripts with it. So, no anger.
- yellowapple 7y ago
  Or, of course, one of the numerous Expect-like tools for other languages/ecosystems, if that's more one's cup of tea.
dragonwriter 7y ago
That's not “do-nothing” scripting, it's orchestration scripting for a process where the steps are executed by a human. It's basically the minimal version of a standalone workflow automation; it's got crappy state storage and is really only good for a single human execution unit per script (or perhaps multiple swapped sequentially rather than in parallel), but it's an instance of a fairly well-known class of do-something software.
peterwwillis 7y ago
That's actually a runbook. But it's a pretty good idea to make your runbook into code! This is a nice, gradual way to begin automating. You automate one step at a time, easiest tasks first, until eventually all of it is automated. The more your steps are reusable, the easier it is to automate other tasks. An example is approving new users to access a service. Say your list of users is a YAML file. Someone edits the file, fires off a PR, waits for someone to approve it, merges it, and applies the config. You might think it's so easy to do by hand, automating it would be a waste. But if you actually add up the time it takes for humans to do those steps, plus the lead-time from creation to completion, plus the occasional typo, wrong username, or Norway bug, it can take from hours to days to actually complete the task. By automating steps one at a time, you gradually move toward the entire process being a single script that takes a username, and completes the task in about 30 seconds. This is a small win, but added up over all your operations, reduces hundreds of hours of toil and reduces human error. If every engineer automates one step of one runbook per week, over a year you'll have hundreds of reusable automation steps. To the OP, I'd add the following: 1) use the least-complex way to accomplish the task. If you don't need to write Python, don't. Bourne shell is your friend. Re-use existing tools and automated features. 2) Add documentation to the code that can be auto-generated, so you can use the script as long-lived static documentation. Documenting somewhere else will lead to stale docs. 3) Run all your runbooks from a Docker container. 4) Plan to run these runbooks-in-containers from a CI/CD system using paramaterized builds. 5) Organize your reusable automation steps by technology, but have product-specific runbooks that call the automated features. 6) In a big org, a monorepo of automation features is an efficient way to expose automated features to other teams and ramp up on shared automation quicker.
m463 7y ago
I do the same sorts of things for my scripts. I start with my "template" script and fill it out. totally over-engineered for most tasks, but then as the tasks mature they have a firm foundation. very simplified example: #!/usr/bin/python import sys,os,argparse parser = argparse.ArgumentParser(argument_default=None) parser.add_argument('-d', '--debug', action='store_true', help='debug flag') parser.add_argument('files', nargs='*', default=[], help='files to process') arg = parser.parse_args() def die(errmsg,rc=1): print(errmsg, file=sys.stderr) sys.exit(rc) if not arg.files: die('filename required')
banku_brougham 7y ago
Implementation question: Whats a good way to generalize such a python script so that windows and nix users can run it?
- alexis_read 7y ago
  The best way is probably a bootstrap script ie. ps1 or sh which supplies the platform-specific parameters, and can pip install any script dependencies. So, 3-file solution. Additonally, this can be generalised to a CI platform as python can subprocess-run anything there's not a native lib for. Lastly, you could do autodoc via the script for a complete solution.
vagab0nd 7y ago
I did something very similar just recently. I have a calendar event to backup all personal data every 3 months, based on a checklist. I'd always wanted to automate it but every time I tried, it just seemed such a daunting task that I never ended up doing it. Last time, I figured I'd start going at it gradually. So what I did was I turned the checklist into a bash script, telling me what to do at each step. I also implemented the ones that are easy to automate. The plan is to knock out two or three items each time I do the backup, until it's fully automated.
xtat 7y ago
I do this!
punnerud 7y ago
When I can (often): 1. Write SQL to automate 2. Put SQL with output in Metabase 3. Have it manually checked alongside day-to-day operation 4. Iterate 1-3 (you often will get a lot of feedback) 5. Replace the manual work, now that the SQL it checked on a lot of cases in production
deleted 7y ago
[deleted]

645 points by thameera 7y ago

Combined with the concept of literate programming this would also help capture the "why"s of the slog, resulting in inline documentation. Jupyter and org-mode for the win!

ben509 7y ago
Running such a checklist in Jupyter seems like a very good approach. The big advantage is someone else can pick up from where you started. And reporting is built in as you can save the notebook and review it later. The only thing it lacks is control flow. A good operations script has exit points: if an operation fails, you often want to rollback and abort. Though even there, you can save state in a variable and have a check.

phoe-krk 7y ago

They are do-nothing scripts but it isn't equivalent to say that the scripts do nothing. That is a very important distinction to me. These scripts organize tasks into flows in a way that makes it possible to split work by logical checkpoints. The tasks between these checkpoints are dependent on one another in the overall flow, but have independent implementations that can be delegated to software or done by humans.

kostarelo 7y ago

It seems to me that all you want is to document a manual process. Having them documented in dump scripts is no different than having them documented as a guide in your knowledge base .e.g in Confluence or as product requirements. I can see the usage in an isolated team of a few people that will write these scripts for their own benefit. I am opposed in general with having scarce information around. Better have everything a single place, whether that's a guide on how to provision a user or is how to add a new endpoint to your API or write a new end to end test.

TuringTest 7y ago
There is one advantage of this script over an equivalent document: it provides the instructions in the same context that it's being used (the command shell). Unless we have script shells that can universally launch a web document side-by-side from the shell prompt where it needs to be used, having it being displayed from the shell itself step by step will reduce the mental load required to follow the instructions. Also, the benefit of having an already semi-automated process in order to build a script in the future is not negligible.
- pojzon 7y ago
  I think dual screen solution provides exactly that. Working only on a corporate laptop is very inefficient in this regard.
lucideer 7y ago
In addition to the sibling commenters point about providing instructions in context, this approach has another much bigger advantage (mentioned in the article): it informs you of where you are in the process so you don't miss steps. Keeping track of which step you are on while following a long doc is no easy task when some steps needs to be left unattended (and produce scrolling terminal output making viewing the last-run command harder).
some_furry 7y ago
Furthermore, some tasks are nonlinear in complexity. Documenting those properly would quickly lead to a "choose your own adventure" type scenario. Most documentation software (i.e. Wikis) do a poor job of encapsulating this. The "do-nothing" scripts might be easier to maintain, but it forces you to use plaintext. I recently started an open source project that might be more helpful for teams (if for no other reason than it uses Markdown): https://faq.dhol.es/@Soatok/public-beta/what-is-faq-off https://faq.dhol.es/@Soatok/public-beta/what-is-faq-off
iainmerrick 7y ago
Having them documented in dump scripts is no different than having them documented as a guide in your knowledge base It’s very different, in at least two ways: - If your checklist is on a wiki, people may stop referring to the checklist once they’re familiar with the process. That’s bad if there are important changes. But if the process is “run this script and do what it says”, I think people are much more likely to keep doing that. - When you start automating steps, people using the checklist pick up that automation for free. With a checklist on a wiki, any new automation means the user has to do something differently (eg maybe step 10 is “run this script” instead of “log on to the dev console and disable write access”)

probablyfiction 7y ago

This just seems like checklists with extra steps.

TuringTest 7y ago
That you can run from the shell.
rusticpenn 7y ago
but this can be gradually automated with less effort than a checklist.

darkerside 7y ago

I love things like this. Mindbendingly simple ideas that rely purely on overturning preconceived notions about what things are "worth" a certain amount of effort. There's a tautological, cart-before-horse paradox in many cases.

sourceless 7y ago

This seems like a surprisingly powerful and should-be-obvious kind of idea... I think I'll start making use of it!

heinrichhartman 7y ago

Very nice idea, Dan! This reminds me of the power of checklists that has been discussed here a few times: Simple but highly effective. It allows for a pretty natural transition: - (Markdown) Manual - Do-nothing-script (printing out the manual in steps) - Partial automation - Full automation

praptak 7y ago
The reference article for the power of checklists: https://www.newyorker.com/magazine/2007/12/10/the-checklist https://www.newyorker.com/magazine/2007/12/10/the-checklist Another article, with HN discussion: https://news.ycombinator.com/item?id=20293246 https://news.ycombinator.com/item?id=20293246

crispyporkbites 7y ago

Are there any good slack plugins out there that can do this kind of workflow/ state management?

NateEag 7y ago
I don't understand why you would want to introduce Slack to this. What benefits would that give?
- crispyporkbites 7y ago
  Slack is like the shared OS we never had
  - NateEag 7y ago
    I'm sorry, I still don't understand. The only interpretation of that I'm coming up with is that each step of the process would be kicked off in Slack. Wouldn't that mean people could easily stomp on each other's toes? Wouldn't there also be tons of needless noise as each of us does our workflows? I use Slack daily, but we don't have any automation hooked up in it. I realize some teams drive deploys, alerts, and other stuff through it. That makes sense to me - this does not. Am I missing something?

fredley 7y ago

I can't help looking at this and working out how to build a tool that can generate a Do Nothing script straight from your histfile, making the business of archiving the commands you just executed as easy as possible too...

jasonjayr 7y ago
If you're about to do a sequence of commands into a terminal, you can create a transcript with the 'script $filename' command ('script' command is in the util-linux package', according to the man page), and it will capture input/output into the transcript. This would probably make this task easier, since you could see the output data, and how the output data is transformed into arguments into the next command ...
- vfinn 7y ago
  Came to say this. https://www.youtube.com/watch?v=tweyWNr6X18 https://www.youtube.com/watch?v=tweyWNr6X18
alexanderdmitri 7y ago
Reminds me of the time I decided to try kanban to start moving forward on tasks I procrastinate on or have trouble starting. Of course, to make sure it was efficient enough to be helpful it had to be a configurable terminal app I could quickly update and review via cli and abundant io flags/options. It also made sense to write it in Scheme because I had been thinking I wanted to try Lisp earlier that day. Fast-forward three weeks and I find myself hopelessly trying to refactor this strangely ugly-beautiful ascii-art themed effort tracker run by an abomination of labrynthine "functional" source and realize (maybe just finally admit to myself) it was all an excuse to avoid all that shit I'd convinced myself I was going to acheive by kanbanning in the first place. The best part is I regret nothing!
- jgwil2 7y ago
  Lnk src pls

2T1Qka0rEiPr 7y ago

Nice idea! I'm actually in the process of automating a task bit by bit. Unfortunately it's with the intention of moving it into a CI pipeline, so the "success" there is rather binary, but I will most definitely adopt this process in future.

grecht 7y ago

Great idea! From personal experience I can say that there are some things ops teams never get around to automate, either because there is always something more important to do, or because it would be too expensive to have a developer spend time automating them. This is a simple, quick solution that solves the problem of accidentally skipping a subtask, thus screwing something up and feeling stupid for doing so.

gtf21 7y ago

This is a really great idea, and appealing in its simplicity -- I think we might try to implement this in my company for some of our tasks which are really very manual, but for which automation is a daunting task.

nerdponx 7y ago

I get it, but this script looks a lot like a checklist to me. Seems like a checklist is a good place to start, no? If you want more "interest" during the process, make it a point to refine the documentation for your process (clarify a step here, split one command into two steps). Then you have a very clear spec by the time the process needs to be automated.

wtetzner 7y ago
I think the value of using a script as your checklist is that the script can handle some of the book-keeping for you, including making it harder to lose track of where you are.
- maaaats 7y ago
  It also documents the process, which is often lacking for these one-offs tasks.
pixelrevision 7y ago
Each part of a script can be replaced with actual code over time without committing to trying to automate the entire thing. I think it’s a pretty nifty idea that helps avoid putting the whole thing off for later.

victormours 7y ago

This idea is great. You could even argue that these scripts actually do something: they allow storing and updating the state of a process. By having these scripts run in a shell rather than in your head, the current state is stored in a machine, not in an unreliable human brain.

empath75 7y ago
also they allow you to gradually script stuff as you figure it out.
- rakoo 7y ago
  This should be read in conjunction with this other great article about how to gradually automate your process: https://queue.acm.org/detail.cfm?id=3197520 https://queue.acm.org/detail.cfm?id=3197520
  - mturmon 7y ago
    This is a great article, providing even more context for why this stepwise automation is smart.
- lioeters 7y ago
  That looks to be a big advantage of scripts like this, they allow the gradual automation of processes. I realized that I've written scripts that are "executable checklists", but didn't see it as a design pattern until reading this article. Typically such a script starts out as fully manual (do this, do that next, copy here, paste there..) then I replace steps as actual code, where I can, while some steps remain manual if needed. Great use of such checklist scripts is on-boarding collaborators or new team members in a project. Also, as grandparent comment pointed out, they reduce cognitive load by keeping the state of a process outside the head.
- jonathanpoulter 7y ago
  this seems like the real magic here. The author states at the start, automating all of the steps of something can be daunting. But this script can incrementally become a do everything script.

js8 7y ago

Seems basically to be a checklist. However, I don't think it's a good idea. Checklists are not bad, but they are to be executed by humans. I think trying to automate an existing human process directly is a mistake. Human processes often have features that only humans can do, such as pattern recognition or adapting to small difference. It's often easier to create a computerized (automated) process from scratch than to try to account for all the edge cases that humans might have to deal with (and do without problems). (The opposite is also true, processes that computers have no issues with can make trouble for humans. For example, humans have imperfect memory. So if the process asks humans to keep track something for extended periods, it can be difficult.)

iainmerrick 7y ago
Well, the specific problem it addresses is: 1. We have a tedious manual checklist 2. We’d like it to be fully automated 3. How do we get there from here?? You’re correct to say that if the process had been fully automated from the start it may well have been implemented very differently. But those scripts are hard to write, and basically useless until they’re complete. Often the only practical way to do this stuff is incremental refinement, where each small step adds a little bit of value. The trick is figuring out where to begin. I think the suggestion in this post is a wonderful way to get over that first hurdle.
- js8 7y ago
  You can do automation incrementally, but it's quite a different mindset to automate computer than to write a checklist for humans. If you try to emulate a person with a checklist, then you will often find it is actually harder to automate, because the steps often rely on human adaptability and common sense.
  - iainmerrick 7y ago
    What other approach do you suggest, then, in the extremely common scenario where you have an existing, tedious yet reliable multi-step manual process, and you’d like to automate it?

timwis 7y ago

What is the value of this over a checklist?

mattacular 7y ago
It's explained at the end of the post.
crispyambulance 7y ago
I would argue that it _is_ a checklist. The difference is that it's a more gradual entry to automate the task. One could, for example, replace any item with a script/program invocation, while leaving the others untouched. It's an intelligent, piecemeal step towards automation. I would also add that in really critical tasks, one could automate _either_ the item, or it's verification. Sometimes it's easier to check that something is correct than to do it-- or vice-versa.

swiley 7y ago

Is anyone else bothered by how they were handling ssh keys in the example? The whole point of public keys is that the private key never has to leave the box it’s generated on. Once you go sharing them you might as well just use a random passphrase.

deg4uss3r 7y ago
Yes, very much so. In addition stop using RSA[0] and use ed25519 with `ssh-keygen -t ed25519` [0]: https://blog.trailofbits.com/2019/07/08/fuck-rsa/ https://blog.trailofbits.com/2019/07/08/fuck-rsa/
- viraptor 7y ago
  Unless you're using a hardware token via gpg-agent. In that case RSA is the only way most of the time.
  - xemdetia 7y ago
    Yeah hopefully when FIPS 140-3 finishes we'll start seeing hardware tokens that can do elliptic curves.
- devonkim 7y ago
  Because Jenkins has its own ssh client, that wasn't supported as of last year with elliptic curve based keys and I had to re-launch a bunch of servers in production to downgrade back to RSA or DSA keys because they were basically the only key types that Jenkins supported. Really not sure why Jenkins had to go this far to re-invent a cryptographic wheel (besides the usual "support both Windows and Linux" angle).
wtetzner 7y ago
Yeah, at our company things are done in the reverse of that script: the user generates their SSH keys, and there's a process they use to register the public key with the rest of the system.
- 7y ago

dusted 7y ago

We use this at my place, though in bash, and we call it executable documentation. Stuff like: NAME="$1" # Create directory for the code mkdir "$NAME" # Checkout the source cd $NAME && git something # and so on Sometimes with an echo "You need to read and understand this before just using it"; exit 1 thrown in somewhere for good measure. These files will have no logic, and make very little use of variables. They will also have a .txt filename to ensure that people understand, that first of all, this is a set of instructions for how to do something, which just so happens to be a valid bash script.

dharmab 7y ago
We embed similar explanatory docs in Markdown. A short example for dig from our troubleshooting guide: # General form dig @<resolver> <record> dig @1.1.1.1 www.example.com # Omit the resolver to use the system's configured resolvers dig www.example.com # Don't need the full output? dig +short www.example.com
meowface 7y ago
This sounds like basically what I use READMEs or supplementary Markdown documentation files for, just in a bash code block in a Markdown file rather than in a bash file.
- peterbell_nyc 7y ago
  The difference is that every time you do the process, you can consider writing a couple of tests and automating the step.
  - meowface 7y ago
    That's true. I guess I tend to just use those as examples/documentation at the start, and then when I want to automate the process, I do it more in an all-at-once way (with a Python project or something) rather than incremental additions to a bash script. Do-nothing scripting does definitely sound like a technique I should try out. I'm not a huge fan of bash for stuff beyond a list of short commands/steps, though.

Ididntdothis 7y ago

We do a similar thing for tests that are hard to automate. Instead of having the test protocol in a document it’s in a script that prompts the user to do things. The observations are then recorded and stored.

persephonee 7y ago

raw_input is python 2.x. Dont use it.

klmr 7y ago

I know this isn’t the point of the article but the code shown there is the archetypal case where writing classes is an anti-pattern, as argued in “Stop Writing Classes” [1]. All the classes in that code can — should! — be functions. There’s no downside, and it’s less code (and otherwise identical). [1] https://news.ycombinator.com/item?id=3717715 https://news.ycombinator.com/item?id=3717715

naringas 7y ago
maybe he was a Java programmer? all joking aside, the reason he's doing classes seems to be an intention towards making a FooStep (and/or a BarStep) which could then maybe handle generic Foo stuff (authentication comes to mind) in the future?
- epr 7y ago
  "maybe"..."in the future" is the root of much object oriented evil
  - shareIdeas 7y ago
    I don't think there is a correct answer, but I like that a developer has foresight.
    - mattnewton 7y ago
      The problem is you get more information in the future, but all this boilerplate is has been written before that information so the first instinct / seemingly least-resistance thing to do is to fit the new information into the old boilerplate / hierarchy. Lots of people have OO scar tissue from getting weird impedance mismatches on newish OO systems designed this way.
    - sullyj3 7y ago
      Real foresight is understanding the cost of unnecessary technical debt.
    - 7y ago

dradtke 7y ago

Anyone interested in this idea should check out https://github.com/braintree/runbook https://github.com/braintree/runbook

beat 7y ago

I'd go farther... you can have steps that literally "do nothing". They can be comments, or simple echo statements. They're placeholders to remember to write the code for that step later. This is particularly important when you need to deal with integration that isn't necessarily easy - handling auth credential safely, making sure it works in your pipeline, etc. But all this gets back to something I used to say a lot, and the more refined version I say now. I used to say "Have humans do what humans do well; have computers do what computers do well". The key part of that was the idea that computers can't do what humans do. Now, I say "Anything a computer can do well, a human cannot do well". Which includes those pesky twenty step manual processes.

dkarp 7y ago
But these steps already do nothing except say echo what should be done. How does that differ from your "literally do nothing" steps?
- winkeltripel 7y ago
  my hot take is that it differs is that you plan to never automate some of the steps, if they're steps for a human to do. As part of onboarding, you might send out an email introducing this new human. The "description" field of this new human should be written by a person, not scraped from their linkedin or google, and summarized to less than 100 words by a computer.
- beat 7y ago
  In a truly minimal system, there isn't even a prompt. A code comment is about as minimal as I know how to get. That's just a placeholder to remember to automate a step. When automating a complex manual process, the first thing I do is write comments describing the sequence, and any parameters needed. Parameters in particular can be enlightening, because when manual processes grow organically, naming consistency becomes a source of suffering - humans can just sort of figure out the right thing to type, computers can't intuit these things and they must be made explicit. It's worse when it can't be explicit without updating the process or creating some sort of data store for mapping. This is why naming things is one of the two hard problems in computer science.

abathur 7y ago

This feels like a useful concept. I stumbled into doing roughly the same in my macOS system bootstrap script. I found it from the other side, though--usually only after failing to find a good way to automate a step, or realizing automation would be vastly more complex/fragile than just prompting myself to do something manually at the right time. Probably a more useful concept when it's conscious from the getgo. :)

chousuke 7y ago

In situations where using full-blown configuration management has too much overhead I often do something like this by just copying the commands I run into a script to begin with. It allows me to easily generalize a sequence of actions into a do-nothing template and doubles as documentation. I'm very much against documenting concrete steps in a wiki if it is something that can be scripted. Such documentation becomes something that you must maintain, and faulty documentation is worse than no documentation. I think that wiki documentation should be used to summarize workflows and provide context, but if you're writing step-by-step instructions, often you can just write a script with exactly the same amount of effort.

nmca 7y ago

This is a checklist. Checklists are incredible, and I quite like this version.

lazyant 7y ago

Checklists as Code

X6S1x6Okd1st 7y ago

It's a checklist

nlawalker 7y ago

Suggested upgrade: Have such scripts ask for a unique name/"instance identifier" when run so they can log to simple text files in a well-known directory and potentially pick up where they left off. For when you invariably use these for long-running tasks and have 7 of them in-flight, and your power goes out or Windows forces a reboot.

marshmellman 7y ago

An additional benefit of this approach is that your checklists now get code reviews, git hooks, history, etc. for free. I mention this because I worked at a company where checklists were typically simply added to a wiki and required separate processes for things like peer review.

manas666 7y ago

if you are working at a small shop or startup - then whatever makes you happy, even these classes are OK. if you are working at enterprise - then these processes gotta be implemented according to ITIL in a specialized IT Service Management system - like ServiceNow, which allows building process flows like directed acyclical graphs and automation of necessary steps

oblio 7y ago
I'm not sure if this is ironic. I've been numbed by too many years of internet usage, I guess :-)

andrewguenther 7y ago

I have a script in our automation setup called "be-the-change" which takes either markdown or a wiki url as a parameter. It will output the markdown or wiki content, wait for the user to confirm they've completed the steps and then print: Doing manual steps sucks, wouldn't it be great if this was automated for the next person? Be the change you want to see in the world.

orestis 7y ago

I like the checklist nature of this. I approached this problem from another side, which involved a very powerful REPL, but lacked the structure this shows: https://orestis.gr/clojure-unlocking-incremental-automation/ https://orestis.gr/clojure-unlocking-incremental-automation/

pgt 7y ago

This is a good idea. I recently wrote down some ideas about "How to Grow a Program," in a symbolic programming environment: https://github.com/theronic/hoist/ https://github.com/theronic/hoist/ I call it Hoist - from "hoisting up" concrete, hard-coded values into abstract symbols for reuse. It's complete vaporware at this point, just a place to collect my thoughts for a future essay.

teddyh 7y ago
See also: In TDD, there are defined steps you go through as you gradually refine your code to actually do more and more things; from returning nothing, to returning one value, to returning a list, etc.

mbar84 7y ago

Interesting idea! I'll wrote some boilerplate that I think is a bit nicer: https://gist.github.com/mbarkhau/60fc4bbe505914369ebd2fec1ab6d21b https://gist.github.com/mbarkhau/60fc4bbe505914369ebd2fec1ab...

AstroJetson 7y ago

Why do I think that writing a script in Expect (https://en.wikipedia.org/wiki/Expect https://en.wikipedia.org/wiki/Expect) would take as long as doing this and then you would be done?

moonbug 7y ago
..because you've never tried using expect in anger?
- AstroJetson 7y ago
  Nope, I like Expect, it's my friend and I'm able to make scripts with it. So, no anger.
yellowapple 7y ago
Or, of course, one of the numerous Expect-like tools for other languages/ecosystems, if that's more one's cup of tea.

dragonwriter 7y ago

That's not “do-nothing” scripting, it's orchestration scripting for a process where the steps are executed by a human. It's basically the minimal version of a standalone workflow automation; it's got crappy state storage and is really only good for a single human execution unit per script (or perhaps multiple swapped sequentially rather than in parallel), but it's an instance of a fairly well-known class of do-something software.

peterwwillis 7y ago

That's actually a runbook. But it's a pretty good idea to make your runbook into code! This is a nice, gradual way to begin automating. You automate one step at a time, easiest tasks first, until eventually all of it is automated. The more your steps are reusable, the easier it is to automate other tasks. An example is approving new users to access a service. Say your list of users is a YAML file. Someone edits the file, fires off a PR, waits for someone to approve it, merges it, and applies the config. You might think it's so easy to do by hand, automating it would be a waste. But if you actually add up the time it takes for humans to do those steps, plus the lead-time from creation to completion, plus the occasional typo, wrong username, or Norway bug, it can take from hours to days to actually complete the task. By automating steps one at a time, you gradually move toward the entire process being a single script that takes a username, and completes the task in about 30 seconds. This is a small win, but added up over all your operations, reduces hundreds of hours of toil and reduces human error. If every engineer automates one step of one runbook per week, over a year you'll have hundreds of reusable automation steps. To the OP, I'd add the following: 1) use the least-complex way to accomplish the task. If you don't need to write Python, don't. Bourne shell is your friend. Re-use existing tools and automated features. 2) Add documentation to the code that can be auto-generated, so you can use the script as long-lived static documentation. Documenting somewhere else will lead to stale docs. 3) Run all your runbooks from a Docker container. 4) Plan to run these runbooks-in-containers from a CI/CD system using paramaterized builds. 5) Organize your reusable automation steps by technology, but have product-specific runbooks that call the automated features. 6) In a big org, a monorepo of automation features is an efficient way to expose automated features to other teams and ramp up on shared automation quicker.

m463 7y ago

I do the same sorts of things for my scripts. I start with my "template" script and fill it out. totally over-engineered for most tasks, but then as the tasks mature they have a firm foundation. very simplified example: #!/usr/bin/python import sys,os,argparse parser = argparse.ArgumentParser(argument_default=None) parser.add_argument('-d', '--debug', action='store_true', help='debug flag') parser.add_argument('files', nargs='*', default=[], help='files to process') arg = parser.parse_args() def die(errmsg,rc=1): print(errmsg, file=sys.stderr) sys.exit(rc) if not arg.files: die('filename required')

banku_brougham 7y ago

Implementation question: Whats a good way to generalize such a python script so that windows and nix users can run it?

alexis_read 7y ago
The best way is probably a bootstrap script ie. ps1 or sh which supplies the platform-specific parameters, and can pip install any script dependencies. So, 3-file solution. Additonally, this can be generalised to a CI platform as python can subprocess-run anything there's not a native lib for. Lastly, you could do autodoc via the script for a complete solution.

vagab0nd 7y ago

I did something very similar just recently. I have a calendar event to backup all personal data every 3 months, based on a checklist. I'd always wanted to automate it but every time I tried, it just seemed such a daunting task that I never ended up doing it. Last time, I figured I'd start going at it gradually. So what I did was I turned the checklist into a bash script, telling me what to do at each step. I also implemented the ones that are easy to automate. The plan is to knock out two or three items each time I do the backup, until it's fully automated.

xtat 7y ago

I do this!

punnerud 7y ago

When I can (often): 1. Write SQL to automate 2. Put SQL with output in Metabase 3. Have it manually checked alongside day-to-day operation 4. Iterate 1-3 (you often will get a lot of feedback) 5. Replace the manual work, now that the SQL it checked on a lot of cases in production

deleted 7y ago

[deleted]