Adrift on a sea of code

I open a new codebase, and the README sits empty. I revisit an old codebase, and the vignettes I wrote don't run.

I'm tempted to close my laptop. Never look at these repos again. Increase efficiency by abandoning a side project once a month instead of once a year.

A place to begin

But when we build stuff we want someone to use it. Even if it's just ourselves six months from now. People will fall through our projects’ cracks if we don't provide anchor points for understanding.

Sure, we could tell them to just throw an agent at the codebase. It might work! But anchor points retain their value. Otherwise an agent could be technically correct, but focus on the least relevant parts of our code. Ask me how I know.

I've written about how to create a decent README. Vignettes are great. But documentation goes stale. Faster than seems possible. And it's one of the easiest parts to “get to later.” What are some more minimal, sustainable anchor points that give people a place to start?

Marking the path

If people can't install your tool, the tool doesn't exist. The more “obvious” you think the install process is, the more important it is to display that process prominently.

I'm a big fan of writing —help style docs, even when you're not building a CLI tool. Doesn't feel minimal enough? A short FAQ doc can help people get unstuck a lot faster vs. assuming no one will have difficulties.

You can also create skills to guide people. Think of them as interactive cookbooks that show off your tool’s capabilities. Here's an example for slide-crafting with Quarto by Emil Hvitfeldt.

Something > nothing

When in doubt, any anchor point beats a missing README. Yes, even when that anchor point winds up stale. A map with a slightly wrong path often beats no map at all.

A data thing I liked

DuckDB internals: Why is DuckDB fast?

A not-data thing I liked

A playthrough of Fallout: New Vegas where the player only has one life and isn't allowed to heal