The notes a developer keeps so the work compounds

Last week I fixed a CORS error I had fixed twice before. I know I had fixed it twice before because the third time I finally went looking and found two old Slack messages, three browser tabs of Stack Overflow questions I had upvoted, and zero notes. The fix took about ninety seconds once I remembered which Stripe webhook header was wrong. Remembering took about forty minutes.

This is not a productivity post. It is the inverse of a productivity post.

The thing developers say they want is to be more productive. The thing they actually want is to stop redoing work. These sound similar and are not. Productivity is about doing more in the same time. Compounding is about doing the same thing fewer times. Most developer-productivity content is the first one. The second one is rarer and matters more.

A note compounds when the next time you encounter a related thing, the note is right there, indexed by something you would actually search for. A note does not compound when it lives in a folder called learnings/2024/q3/random.md and you can only find it by remembering you wrote it. Most notes are the second kind. They are write-only memory. The act of writing them feels productive — it produces an artifact — but the artifact never gets read, because the index for retrieval is your memory of having written it, and your memory is the thing that failed in the first place.

What changes when notes compound is not the speed of any individual task. It is the slope of the curve over a year. You start to recognize patterns in your own debugging without trying. You stop having strong opinions about tools you have never used in production. You write a deploy script and then, six months later, write a different deploy script in a different repo and notice that your past self already solved the timezone-handling problem you are about to solve again. You read the old solution. You copy the relevant lines. The whole thing takes four minutes instead of an hour, and the four minutes feels boring, and the boring feeling is the point. You have made yourself more boring at solving solved problems, which is what frees you up to be interesting at unsolved ones.

The mechanics of this are not complicated and they are not subtle. A bug solution needs to be findable by symptom, not by your memory of fixing it. An architecture decision needs to be findable by the question it answered, not by the date it was made. A good prompt needs to be findable by the kind of output it produced, not by which project it was for. The common shape is: index by the future query, not by the past context.

Most note systems get this exactly backwards. Notion's default is a folder tree, which is the past-context model. Apple Notes is a flat list sorted by edit date, which is no model at all. Logseq and Roam are closer because they make linking cheap, but a link only compounds if you actually link, and most people stop linking after two weeks. The tool is necessary and not sufficient. The discipline is to log things you are not sure you will need. A surprising fraction of them turn out to be the things you need.

I used to write essays about productivity. I do not anymore, because most of the productivity essay is wrong about its own subject — it is trying to make you faster at things you should not be doing, instead of trying to make you do them once.