Mike Cann

30 minutes ago

Introducing Convex Explained

Hi i’m Mike a DevX Engineer here at Convex.

Mike giving his end-of-video cheerio salute

So I have a bit of a problem (and no its not drinking too much tea).

A big part of my job is explaining how Convex works, and I'm no longer sure what format that explanation should take.

For years the answer was easy. Write a blog post or make a video. I've done plenty of both. The Convex YouTube channel is full of my videos. But things have shifted a bit lately.

More and more of what reads our docs and posts isn't a person at all, it's an agent. And agents love text. They'll happily chew through ten thousand words of docs without complaining, but they're not much use with a video.

Humans are a different story. A big wall of text is hard work. You skim it, lose your place, and bail halfway through the one bit that actually mattered. Video is great for building intuition, but you can't poke at it, and going at your own pace means hammering the pause button.

So I wanted to try something in between.

Mostly, I wanted reading to be more fun. Clicking around is just more fun than scrolling through paragraphs. It's also how I actually learn things. I don't really get a topic from reading someone describe it. I get it by poking and prodding it and seeing how it reacts.

Convex Explained

The Convex Explained homepage

Convex Explained is a new little site for interactive explainers. Each one takes a single topic and lets you work through it yourself, with demos you drive instead of just read about. It's still text underneath, so agents can read it fine, but the important ideas are things you can click on, step through and break.

I was heavily inspired by nan.fyi's interactive database post, which is well worth a look if you haven't seen it.

Each explainer will also get its own video, so if you'd rather watch than click, you're covered too.

First up, Build Your Own Convex

The first one is Build Your Own Convex.

A common assumption is that Convex is a wrapper around Postgres. It isn't. Convex is its own database, and the best way I could think of to prove that was to build one from scratch.

We start with a plain old JSON file and keep bumping into problems until we've built something that looks a lot like Convex. Every step has a little demo you can play with. You watch data flow between the pieces, step through the code line by line, and break things on purpose to see what happens.

Two users, one hat, two sales

I find seeing it move is what makes it click. Once you've watched two people buy the same last hat, you don't forget why transactions matter. And honestly, it's just a lot more fun than reading about it.

Is this the right format?

Honestly, I don't know yet. This is an experiment. Interactive pages take a lot longer to make than a blog post, and I want to find out if they're worth it.

So if you give it a go, I'd love to hear what you think. Did it work for you? Was it too long? What should I cover next? I've already got one on Batch Worker in the works.

Anyway give Build Your Own Convex a go.

Until next time, cheerio! 👋