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

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

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