Quickstarts and Slowstarts

Tue, 04 Jun 2024 00:00:00 +0000

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.

Tutorial-Writing on Andrew Quinn's TILs

Quickstarts and Slowstarts