READMEscript
🙋👁️📃👁️💻
“If you can read it. You can run it!”
goals
A README that is:
- not just a step-by-step guide for onboarding and setting things up
- a runnable script! (code blocks are executed + interspersed with comments… think jupyter notebooks)
- runnable on all platforms, so maybe something like docker underneath? (or python… or node?). Since you can often assume this would be used to bootsrap other software, it can be used to fetch & set up dependencies, like docker. It would then be a bit unfortunate to have to rely on docker being installed and running. It would be much easier to make this an
npm package, as the threshold for getting widespread adoption there seems much lower. npm i -g readmescript and you’re off and running! (docker has become easier to use, but it’s still not the most straightforward, and often requires adding your current user to a group and logging out & back, or newgrp docker… and npm installs stuff to the systems $PATH with “relative ease” for the complete newbie)
- compatible with existing markdown engines (must render nicely)
- segmented on existing README dividers, where you can run individual sections of a README, eg. to run this goals section, you could do the following:
- maybe there’s a case for using Deno > Node… secure by default is pretty nice… it should integrate with the permissions somewhat to make it obvious what a READMEscript is capable of doing (
--allow-run, --allow-net…)
readme goals
Although running this example section would cause an infinite loop!
design
A block can be written like this:
```bash
echo 'hi'
```
and the READMEscript would understand that this is to be run in a bash shell… but unlike a normal bash script with comments, it has nicely rendered human-readable markdown text around it.
But in order to run a bash script it would need to have something like mingw or docker on the target machine if it’s not running some linux distro with bash available. Perhaps there’s no getting away from requiring docker here.
Perhaps it’s therefore better to use node (assuming the user installed readmescript using npm) and javascript for the script blocks? (with a few of the boilerplate stuff like FS imported?). eg.
console.log('hi');
Bash could also be the default behaviour for when you don’t tag any a code block with any language at all:
```
echo 'hi'
```
why?
often you get a readme that tells you what to do
- create directory
/dir and /temp before running!! (if you don’t it will delete /)
- make a copy of
*.sample.conf files and put them in /conf
- set your environment keys from secrets in SERVICE webgui page
- download
bigfile.txt and set it to be executable with chmod +x, then run it!
- run
start thingy
usually in a bulleted list like the above, but if something is to be written down to be done manually, it may as well be written to be runnable as well.
- people usually start by reading the README (a good convention!)
- usually the readme is opened alongside a terminal or other software (multitasking!), where the user then copy-pastes / follows the instructions described in the README. If the readme is clearly written, the chance of making a mistake is lessened. However if the README is runnable, this should lessen the chance of errors even more.
- if the code is separate from the README, it often leads to the README becoming outdated as experienced contributors have already read the README (a long time ago), and are now happily mutating the code. This results in a jarring onboarding experience for new devs. If the README is frequently run (as entrypoint code), then it should never get outdated!
why not just use another build system, or a Makefile?
- READMEscript would in theory become a replacement for many of the uses of a build system / Makefile. So they do compete in that sense.
- Makefiles are kinda cryptic (unless you have a fair amount of experience), whereas README’s should read a bit nicer.
- most build systems are kinda cryptic tbh… but maybe that’s just my experience 🤔
boundaries?
What should go in the READMEscript codeblocks?
- setup code (copy files, string manipulation, tokens and secrets? (maybe not), resource fetching (prior to package manager ofc)…)
- entrypoint code (run build system -> run the app… eg.
npm run start, or make…)
- very simple snippets & examples (handy for explaining stuff that could be more fitting elsewhere, but are nice to interact with as you read about it)
It makes sense to put entrypoint code in the READMEscript, but at what point does this entrypoint code become configuration code? (better suited to go in its own script file, or config file, Dockerfile…)