About this Site

Motivation for this site

Steve Klabnik learns about projects by publishing documentation about them. I like to do the same thing. That's what this site is. It's me coming to grips with Gas Town, and with dark software factory patters more generally, by reading the blog post and working with the concepts.

Also, I consider sites like Bartosz-style explorable explanations and Andy Matuschack's Working Notes to be just the peak of awesomeness. I want to emulate those guys, to the extent I have the fortitude to do so. They are really next-level. Check them out if you don't know them.

... and at the bottom of this page I'll come clean with you about my real motivation for this site.

Why shouldn't I just read the docs?

Go for it! They're here: https://gastown.dev/docs/overview

But the blog post is the best place to start. It introduces the ideas gradually, with the context you need at each step. Instead of a reference manual, it’s a narrative that walks through the concepts and how they fit together.

That’s why this site is tied to the post rather than the docs.

And if you're going to read that post, why not quiz yourself along the way to see if you really got the concepts at each section? And if you're going to do that, why not do a little repetition so it sticks?

Also, the docs don't go quite as crazy with the dense linking that I find very helpful. That means that in the docs you can't just go to the glossary, then look at a term like handoff and see all the associated backlinks and spaced repetition questions.

Is this site slop?

You know how people are drawing a contrast between vibe coding and vibe engineering? Yeah, this site is more on the engineering side of that equation. Yes, I used some AI. Of course I did! But the site is mostly the result of careful manual study, writing, and linking, with some of the restructuring bulldozing done by AI. I do have AI define a few terms outright, like incremental reading, but I try to make note of that wherever I've done it. I value your time, dear reader.

Wait, don't I have to do the hard work myself to really grok something?

Honestly, I'm not sure. Maybe you do?

I consider it in do you need to write your own spaced repetition prompts? and how I might reasonably keep externally-generated notes in my notes.

Show me your work!

Speaking of person - Andy Matuschak, he has also influenced me to work with the garage door up. So, here's the Scratchpad for this site. It details my hopes, dreams, frustrations, and missteps. It is primarily written for me, but perhaps you'll find some value in seeing me stub my toes over and over.

Ok, as promised, my real motivation for this site

I mean, what I said before is really true. But also...

This site is a great driving use case for the application I'm building. Check out Introducing Meadow.

To support what I really want in this site, Meadow has grown support for publishing spaced repetition cards and hosting the whole site's raw markdown as a downloadable .zip file. I probably would have arrived at those features eventually, anyhow, but I got there sooner because I realized that those features are what I would want if I was reading a site like this.

I'd kill for more of these kind of sites to be in the wild. I love to be bumping into weird Frankenstein combos of Andy's (there he is again) blog post - quantum country, his evergreen notes, with some federated wiki ideas sprinkled in. In my dreams other people publish little sites like this, so I can pull the stuff locally, re-contextualize the atomic concepts contained within the sites, push them around a bit to make them fit my way of thinking, then link them into my existing knowledge graph, and finally publish them as part of new graphs in other compelling ways. In other... "Meadows". See?

The whole space is getting even wilder with markdown graphs and agents. You really can work with other people's ideas (and even agent generated ones). That's basically what I have in mind for Meadow. To me, at least, that looks so beautiful. You see it, right? Right?!? Hey, where are you going?!?