| title | subtitle | date | tags | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Quickstarts and Slowstarts |
How to make an apple pie vs how to create a universe which happens to have an apple pie in it |
2024-06-04 |
|
A while back I stirred up some controversy on Hacker News by talking about why I liked it when tutorials take you from clean VM to working, installed software.
I've since taken to calling this the "tutorial-in-a-box" method. When I write them myself, I usually put them under the header Slowstart, a riff on the proverbial Quickstart. Two examples:
- A gentle introduction to
reposurgeon. - The Slowstart for
selkokortti, some flashcard generating software based around my Finnish language news archive.
The point of a Slowstart is to make it so that even absolute beginners can start to pick up some pointers about how people "in the know" of your chosen software ecosystem actually get things done. Instead of a Dockerfile or a shell script, you take them by the hand, spin up a totally fresh virtual machine from the ground up using something like Vagrant or virt-builder, and walk them through each and every command they need to execute in order to get to a working install.
Slowstarts emphasize reproducibility over speed, accessbility over convenience (not all of us have Docker on the job, or even know what it is), and comprehensibility over magic.
- Because you are starting from a totally-fresh VM, you can present the Slowstart in a totally linear and deterministic fashion.
- Because the reader knows you are starting from a totally-fresh VM, if one of those commands breaks later on, they have absolute confidence that something is deeply wrong, because these commands definitely used to work on this OS, on this version.
The other intention of a Slowstart is that a reader who can't grok the Quickstart at first can work through the Slowstart once to get the necessary skills they need, and then move to figuring out how to get it to work on their tricked-out machine. In an ideal Slowstart, then, each command is like a step in a sketchy but solid mathematical proof, doing only what is necessary, when it is necessary - so that the reader can selectively omit shell commands and see where in the chain that later causes things to break.
I tend to target Debian Linux in my Slowstarts, as I feel that is an
excellent "lowest common denominator" for this kind of work. But if
in your slice of heaven there's a better LCD, for example FreeBSD or
Fedora or Alpine, it makes a lot of sense to just target that and
call it a day. Even when the emphasis is on learning to drive your
own car,
you can still get a lot of valuable practice in your uncle's jalopy.
And who knows - you might just convince someone that e.g.
pkg_add really is nicer than apt install, and make some new friends
in high places.
Best of all, when you come back yourself in 10 years and try to figure out how the heck to get your old bit of legacy software running, you yourself will have confidence that at least at some point, you knew cold how to install it on a certain OS, at a certain version.