Developers want scripts and tools — not “how-to” guides
Does this scenario sound familiar to you?
You want to do X on the command line. You Google search for an article on “how to do X.”
The first result: “How to do X” from developers.x.com, last updated this year.
Perfect! The official docs, and they’re even up to date! Of course, you click on it.
You read through the article, and you copy and paste the commands into your terminal. Before each command, there’s a detailed explanation of what each command is supposed to do, so you feel confident that this article is not going to leave you with a bricked computer.
“Great!” you think to yourself. The commands worked flawlessly, and you got X done.
Two months later…
You want to do X again. But this time, you’re a bit more time pressured. You really want to do Y, but you need to get X done before you can do Y.
So, to refresh your memory, you Google search “how to do X.” You see the same article: “How to do X.”
It lists out the same commands.
You copy and paste each of the commands.
“Ugh, this is so tedious!” you think to yourself. “I don’t want to read all of this! I don’t care about how to do X! I just want to do Y!”
The moral is: if you’re writing some technical documentation or even a blog post on “how to do X” and it involves more than a few commands, your readers would love if you could include a script that runs all the commands automatically for them. They would really appreciate a TL;DR at the top of the article that says something like “Done this before? Get the script here (link).”
A philosophical note
If you have some knowledge about a particular process, you should codify that knowledge. When you take your knowledge of a certain process and turn that process into a script, you are automating that process, creating value by providing a new tool that allows people to be more productive, saving them the time of having to run commands manually and make decisions about whether or not they need to run commands.
As the number of users of your script increases, the amount of time saved increases. This is how we make progress in the field of software engineering — by saving time for cool stuff and automating the boring stuff!
Where to write scripts
GitHub repositories or even Gists are a great choice for storing one-off scripts. In your article, you can instruct readers to run one command to execute your script: eval $(wget -qO- $url), where $url is the URL of the raw file.
If the script starts to get complicated, with lots of user inputs required, it’s probably better to create a full-on Command Line Interface (CLI) with proper flag parsing, and consider uploading it to a package repository like PyPI or NPM.
Let’s get meta: a script that creates new scripts
After writing this article, I realized that a lot of the information in this article could be encoded in a script!
So, I wrote a script called new-script, which creates a new executable Bash script at the path provided as an argument. The generated script contains some basic boilerplate, and is marked executable. Best of all, it gets automatically opened in your preferred editor!
To install it, use this command:
sudo bash -c 'cd /usr/local/bin && wget -qO- https://gist.githubusercontent.com/bduffany/a0cb3a8be0364dae91804ac510670e81/raw/7717ce1911fff3ba19dabc7f4acbb03cd5beda1f/new-script.sh > new-script && chmod +x new-script'Then try running new-script foo.
Making scripts convenient
Scripts can be made even more accessible and usable by providing integrations into various developer workflows.
For example, if a script needs to operate on a particular file as part of the code editing workflow, it might be nice to build a lightweight IDE extension that just runs the script using the currently open file in the editor.
More lightweight alternatives to extensions exist for simple scripts, like Tasks in VS Code or External Tools in IntelliJ.
In my next article, I’ll discuss some useful tips for writing scripts in both Bash and Python.
Thanks for reading!
