[dusted]

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.

[qznc]

You could prefix the script with `#!/bin/bash -vn` and make it executable. It will just print itself.

[thunderbong]

Thanks. Didn't know about this.

[dharmab]

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]

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]

The difference is that every time you do the process, you can consider writing a couple of tests and automating the step.

[meowface]

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.