Proof that keeping a dev diary is worth it

This initially started out as an experiment, detailed in the first section of this post. Proof that the experiment was successful follows in the later sections.

An experiment for devs to try. I started keeping a "dev diary" while working on Breezbook. It was prompted by a statement by Stuart Ervine when I asked how others keep broader context of decisions behind code that are not visible in code, tests or comments.

I wanted to start simple, so it's just one long markdown file. My partner on breez, Metehan Altuntekin, suggested that a tool like Obsidian or similar might be more appropriate. But I'm happy I stayed with a simple text file. I can edit it in my code editor, while I'm coding, without breaking flow.

It's a good sounding board when I'm working on my own. I can write down my doubts and concerns, and just the act of getting them down helps me think them through better.

And I can feed it to an LLM and ask questions, like: remind me why I decided on Inngest for messaging? Or why might the location_id field on service be optional instead of mandatory.

I consider this a worthwhile experiment to try on dev teams. Yes, ADRs, but consider this as an alternative or complement.

The dev diary is here btw.

Exhibit 1 - LLM design assistance

Some time after starting the diary, I felt the design need to shift my modeling of capacity from Resource to Service - because a service might have several resources involved, so what is the capacity in that case.

I had done considerable work getting capacity added to Resource and worried that shifting it would break something. So I asked Claude, and it returned with these very insightful and reassuring insights:

This proves to me that keeping the diary is worth it.

Exhibit 2 - LLM refactoring assistance

Not directly related to diary keeping, but I then asked Claude to help me with the refactoring of capacity from Resource to Service and what it returned was the exact to do list I used to carry it out: