Foreword

I have built software for more than twenty-five years, from the dot com era before the turn of the millennium, back when the title was webmaster and it was an honest one. One person, the whole stack. The box under the desk, the database, the code, the markup, the deploy, and the outage at 2am, all of it yours. You learned everything because there was nobody else to learn it for you, and you carried the whole machine around in your head because the job left you no choice.

I was good at it in a way I could never really explain, and hopeless at almost everything else, and that one I couldn't explain either, and for over twenty years I didn't have the one word that tied those two facts together.

The first serious thing I broke, I broke a few years in, and I broke it hard. Around 2001, long before I had any real system to the way I worked, I deleted a mail server. Not a row in a table. A live server, with real people's mail sitting on it. I spent the rest of that day dragging it back out of the archive, and I've always assumed some of it never came back, that somewhere a message someone needed was just gone because I'd been fast and certain and wrong. What I took from it wasn't that I should be more careful. I had been careful. It was that my care was worth nothing, and anything resting on it was already broken.

So I stopped resting things on it. What I built instead were patterns. Blocks. Pieces I could reuse that had never once let me down, that I could see with my eyes shut. Everything became a block with an edge I could point at, and the edge was a contract. Inside the block I could do as I liked. Across the boundary nothing moved without an agreement written down somewhere. I never reached past the edge of a block on trust, because trust was the one currency I'd learned I couldn't spend. You plug the blocks together. You read the interface and leave the insides alone. You put the blast behind a wall, make the dangerous thing ask twice, keep an undo, and never let the delete work out what to delete in the same breath it deletes it. The simplicity was a handrail I needed so I didn't fall down the stairs.

I thought I was describing good engineering. It took me years to see I was also describing a disability, and that the two were the same thing.

I was diagnosed with inattentive ADHD in my mid-forties, and medicated only recently. I won't pretend it was a small thing. It was a fog lifting. As it cleared I could see how far back it reached, every place I'd run aground and never understood why. I hadn't been unlucky, just drifting the whole time, blown along on a breeze I couldn't feel, good at the one thing I'd built defences around and a mess almost everywhere else. The first time I took the medication, the noise in my head dropped far enough that I could follow a single thought all the way through. I had been an engineer for twenty-five years before I could reliably do that.

Here is the part that made me want to write any of this down. The one room in my life that was always in order was the code, because years before anyone gave the disorder a name, I had already built the structure that beat it. This manifesto is that structure. It's the set of defences I made so that a tired, distractible, overconfident engineer, which is me on most days, could still make a correct change while ignorant of almost everything around it.

I built the first version for the machines. I'd been working with coding agents, and I kept watching them fail the way I fail. Sharp for a stretch, then they lose the thread. They forget the thing three files back. They walk straight past the boundary they should have stopped at. So I wrote them rules. And it occurred to me that the rules I was writing for the machine were the same ones I'd spent a working life writing into my own habits, and that the engineers I'd worked beside, myself first among them, so often came undone for the lack of them. So I wrote them down for people too, the way I wish someone had written them down for me, twenty-five years and one mail server ago.

A word on how it reads. The thoughts here are mine, every one of them, drawn from twenty-five years of my own mistakes, and so are the aphorisms and the judgement on every trade-off. But I had help with the prose. What is in my head arrives as word salad, and I leaned hard on AI to turn it into lines you can actually follow. The voice is mine. The fact that you can follow it, that part I owe to the machine. I think that is allowed. If anything, it is the manifesto doing the thing it tells you to do: put your effort where only you can, and let something else do the rest.

So read it as mine, because it is. But read the commands for what they are. When it says do this, that's me speaking to myself, on a good day, for the sake of myself on a bad one. You're welcome to listen in. I am not handing you a law. I'm handing you what I carried off the battlefield after twenty-five years of losing to the same small handful of mistakes. I dressed it up as principles because that's the only way I'll keep to them myself.

It is my way. I hope some of it becomes yours.

Matt Williams

For more on the person and the story behind this, there is an interview.