blog | oilshell.org
This post is part of "flushing the blog queue", mentioned in the January Blog Roadmap. It links to stories and comments making the same point in different ways:
One thing the author didn't cover is how you can share reified knowledge when you write shell scripts... That is really really powerful, because you can not only share it with others but also with your future self.
Summary: Instead of writing docs with shell commands, I invert that and write shell scripts with comments. I show two real examples:
These scripts are not pretty, but I can clean them up when it's worth it. The key point is to record the information in a low-effort way.
My other comments in this thread:
shuf, and use tmux.
Summary: The first thing I do when working on an unfamiliar project is write a shell script that records everything I did.
Example: Hacking on Kernighan's awk 5 years ago: https://github.com/andychu/bwk/blob/master/run.sh
With 30 seconds of inspection and a minute of fiddling, I can pick up a project after years.
Another meme: Never remember a port number!
It's worth repeating a comment I mentioned in this February 2020 post:
Summary: Oil's release process is a big shell script, developed gradually: https://github.com/oilshell/oil/blob/master/devtools/release.sh. It produces the /release/$VERSION/ tree.
Using shell scripts as executable documention works best if everyone is on a similar operating system. This is often the case in an engineering team at a company, but it's not true in open source.
I've run into this problem on the Oil project itself! Contributors may have difficulty getting started because shell scripts rely on programs/paths that only exist on certain distros.
I hope to solve this problem within the Oil project itself, and then expose the solution to users.
If you think so, take a look at the Oil language!