I literally maintain a conceptual-model.md that describes the “things” in our entire system, how they relate to each other, and some bits about how that maps to the code (the DB schema maps sort of closely to it but sometimes not that close, and so does the API, and that’s ok). I wrote most of the doc myself, but plan to coauthor with LLMs going forward.

So far it’s saved me tons of typing as I add features. I don’t have enough data yet on how well it will guide myself and others when adding stuff that really stretches the model, but I’m also optimistic that it’s a valuable approach.

Harder for brownfield projects of course (and it basically replaces Jira, which would cost me all my social capital if I try), so I won’t be adopting it now. But I will be leaning into long-lived organic, grass-fed assets like conceptual-model.md that‘s critical for evolving the product forward but doesn’t strictly map to the types in the code.

I really enjoyed engaging with the article. Loved the humor sprinkled in, and the humility demonstrated throughout. Some great first-principles clear thinking here.

It’s incredible how too much money corrupts everything it touches.

We run a bunch of services in two very different cloud vendors (one of which used to be DIYed with kubeadm), and also on dev machines with k3s. Takes a while to figure this out and to draw the kustomize boundaries in the right place, but once you do, it’s actually really nice.

Two things work in our favor:

- we’ve been at this for around 8 years, so we didn’t have to deal with all the gotchas at once

- we aggressively avoid tech that isn’t universal (so S3 is OK, but SQS or DynamoDB is not; use haproxy instead of ingress controllers; etc)

We run k8s with several VMs in a couple different cloud providers. I’d love it if I could forget about the VMs entirely.

Is there a simpler thing than k8s that gets you all that? Probably. But if you don’t use k8s, aren’t you doomed to reimplement half of it?

Like these things:

- Service discovery or ingress/routing (“what port was the auth service deployed on again?”)

- Declarative configuration across the board, including for scale-out

- Each service gets its own service account for interacting with external systems

- Blue/green deployments, readiness checks, health checks

- Strong auditing of what was deployed and mutated, when, and by whom

I’m trying out another, what I call the principle of path independence. It’s the idea that the code should reflect only the current requirements, and not the order in which functionality was added — in other words, if you should decide to rebuild the system again from scratch tomorrow, the code should look broadly similar to its current state. It sort of works even though this isn’t a real thing that’s in its training data.

Hilarious quote from her Wikipedia page:

> Shotwell has received particular praise from NASA Administrator Bill Nelson for her "phenomenal" leadership of SpaceX as it developed the Falcon 9 into the "workhorse" of the space launch sector.[19] Nelson had reportedly been concerned in 2022, after Elon Musk purchased Twitter, that it would be a distraction at SpaceX, but became more comfortable after meetings with Shotwell left him feeling reassured that she was in charge of day-to-day operations.

This new direction didn’t become clear to both sides of the aisle in the US until a year or two into Xi’s tenure. If someone else other than Xi had been chosen, we would likely have a very different China today.

One of my favorite things as a software engineer is when you see the third example of a thing, it shows you the problem from a different angle, and you can finally see the perfect abstraction that was hiding there the whole time.

If I accidentally accept bad input and later want to fix that, I could break long-time API users and cause a lot of human suffering. If my input parsing is too strict, someone who wants more liberal parsing will complain, and I can choose to add it before that interaction becomes load-bearing (or update my docs and convince them they are wrong).

The stark asymmetry says it all.

Of course, old clients that can’t be upgraded have veto power over any changes that could break them. But that’s just backwards compatibility, not Postel’s Law.

Source: I’m on a team that maintains a public API used by thousands of people for nearly 10 years. Small potatoes in internet land but big enough that if you cause your users pain, you feel it.

To do the job that swarf does, I found that the bwrap sandbox I’d been using is the perfect place to mount a folder to catch markdown junk and keep it out of the project’s actual git repo. Works great.

But I have no idea where the company currently sits on the spectrum from good actor to fully enshittified.