Writing
33 posts published so far, and the ones that landed hardest were the ones that admitted something. Everything here comes from work actually shipped.
Where a piece first appeared on dev.to it says so and links back. The version here is the canonical one.
What these are and what they are not
Short pieces that each argue one idea, taken from something that actually happened. They are not tutorials and they are not opinion about the industry. A piece gets written when a belief I held turned out to be wrong in a way that cost time, because that is the only kind of note worth anyone else's attention.
The ones that landed hardest on dev.to were the ones that admitted something. Three correct fixes that all failed is the clearest of them: three commits that each added the right tag, all correct in isolation, none of which worked, because the truth was in the rendered output and every one of them was reasoning about the source.
What makes a piece worth writing
One test: did believing the wrong thing cost real time. If the answer is no, the note is a summary of documentation and somebody else has already written it better. If the answer is yes, then the interesting content is not the fix, it is the reasoning that led somewhere wrong while looking entirely sound.
That standard is why there are a dozen of these rather than a hundred, and why several took a year of operating a system before there was anything honest to say. The alias piece is a good example. It is a small bug with a one line fix, and it is worth a page only because of how long it survived and what that says about where the blind spot was.
The through line
Most of these are about the gap between what you believe a system does and what it actually does. Measuring the tail rather than the average. At least once being the only honest guarantee anybody can offer. Snapshotting the approver rather than the role, because a person's job title changes and the record of who signed off must not change with it.
They are short deliberately. Each one is a single argument that you should be able to disagree with in one sitting, and several of them link to the longer engine or solution page where the same idea is worked through properly.
Three correct fixes that all failed
The site was not ranking. Three engineers had each diagnosed it, each shipped the correct fix, and each verified their own change. Nothing improved for a year.
Read the output, not the source
When a bug has beaten several competent people, the shared assumption is the suspect rather than their competence. In my experience that assumption is almost always that the code says what the system does.
Why adding more workers made it slower
The queue was backing up, so I doubled the workers. Throughput went down. I assumed I had not added enough, doubled them again, and made it considerably worse.
When one number has four owners
A clerk quoted a balance to somebody standing at the counter. The customer opened the portal on their phone and saw a different number. Both had come from the same system, and both were defensible.
At least once is the only honest guarantee
Exactly once delivery is sold constantly and cannot be delivered across a network. The useful move is to stop wanting it, because the thing you actually need is achievable and much simpler.
Snapshot the approver, not the role
The approval record stored a role. Looking it up a year later returned whoever currently holds that role, which produced an answer that was confident, plausible, and wrong.
Measure the tail, not the average
Average response time is the most reassuring metric available and one of the least useful. It is dominated by the requests that were already fine.
Migrations while people are using it
The dangerous migration is never the complicated one. Complicated migrations get planned. It is the single line that looks obviously safe and gets run on a Tuesday afternoon.
The alias you forgot
Soft deletes work perfectly until the first time somebody drops to raw SQL for performance, and then they fail in the quietest and most embarrassing way available.
What I write down, and why
I write for a hypothetical successor who never arrives. The documents turn out to be almost entirely for me, six months later, having forgotten everything.
Dense screens are a different craft
I redesigned a screen used all day by staff with a queue in front of them. It looked considerably better and it made their job slower, which took me a while to accept.
The two minute rule that decides whether a site survives
A site that launches beautifully and lists last year's prices is worse than no site at all. That outcome is decided at build time, not by the client.
Where to start
- Start here
- A site that ranked as one page, three fixes that were each correct, and why reading the output is the only thing that settled it.
- The counterintuitive one
- The work was contention bound, so concurrency bought queueing rather than throughput.
- The one I would defend hardest
- Nobody can sell you exactly once across a network. Make a second run harmless and you stop needing it.
Common questions
- Are these the same as the dev.to posts?
- Some are, rewritten and usually longer, and where a piece appeared there first the page says so and links back. The version here is the canonical one, so search engines are pointed at this copy rather than treating the two as competing duplicates.
- How is this different from the solutions section?
- A solution page answers a question somebody is searching for while stuck, and is structured for that. These argue a single idea and are structured to be read start to finish. Where the two overlap the writing page links to the solution page, which has the worked detail.
There is more, including the pieces that are opinion rather than engineering, on dev.to .