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…

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

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

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

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

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!

Working towards epic levels of developer productivity at buildbuddy.io

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store