Documentation

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. ...

The best websites are home-cooked meals. Andrew’s Selkouutiset Archive was birthed after I realized there was no obvious way to fetch the previous articles of the “Easy Finnish” daily news broadcast. This annoyed me as a student of the language. “Here we have a stream”, I thought, “of high-quality, human-written, interesting practice material, and no easy way to access it!” So I went out of my way to create such a way, and me and my language skills have been profiting off of it ever since. A very small website, for a very specific need, just leaves a delightful aftertaste in the mouth. ...

Most of us work in companies with something approximating a shared online internal wiki, be it Confluence or MediaWiki or even a searchable, static website custom built for the task. A common problem with these sites is making what you write discoverable to other people on the site. Your chosen title might tell you, a person fully in the weeds of whatever you were just doing, exactly enough to know this is the article you were looking for. Another human being, who might be searching for help on how to do this for the first time? Not so much. ...

Here’s a secret. If you have Vagrant and VirtualBox installed, and your colleague does too, then you can both bring up an near-totally identical blank slate Debian 12 Linux VM by running 1 2 3 4 5 6 mkdir tutorial/ cd tutorial/ vagrant init debian/bookworm64 vagrant up vagrant ssh . This works regardless of whether you or they are on Linux, Mac1, BSD, or even Windows. (Through the magic of aliasing, mkdir and cd even work in PowerShell.) ...

Recommendations appreciated. Disclaimer: Most of these make little sense in an Internet medium anyway. An index. An index simply lists the terms and topics discussed in a document, along with the pages they are listed on. A glossary. Could be as simple as a CSV file of terms and definitions, or as complex as a whole extra glossary/ folder. Related: A “Acronyms and Abbreviations” section. Even moreso than the last, this could be a simple CSV. A built-in site-wide search function. Word gets around this by having everything open at once. A list of tables. Huge if you want your dead-trees books to match your shiny new website. A list of figures. Ditto. A list of referenced external documents. CSV! Say it with me! The reason I compiled this list was because I decided to investigate whether I could use Hugo at work to generate our client-facing documentation. Currently we are using an unholy combination of Word and Confluence, and I figured that the magic of Git might help us keep our docs updated in a more sane way. ...