This is why documenting is so crucial. Even on a software architecture level.
A few months from now, I'd love to have written down decisions for my current project:
- Why did I decided to use Kysely over Drizzle, Knex, Prisma, TypeORM or other ORM/SQL tool?
- How am I going to do migrations?
- Why am I using one of Deno/Bun over sticking to nodejs?
- Why did I structure the project as a directory per feature over controllers/models/services directories?
- Why did I fork this library and what are the steps to keep this thing updated? Do I plan to upstream my changes? Is there a GitHub issue or PR about it?
- Why am I hosting in one of AWS/GCP/Azure? Why not lambda functions? Why docker?
- Why did I pick this specific distribution of kubernetes over the other also lightweight alternatives?
- Why did I even start this project and what do I aim to accomplish with it?
So I created a # Decisions section in README.md
This way I don't keep doubting my own decisions and wasting time opening 20 documentation tabs to compare solutions yet again.
I use GitHub Issues for this. It works so well - any time I make a decision I drop a comment on the relevant issue (often formatted as "Decision: ..."). Now they are archived, searchable, accessible via API and easy to navigate to from my source code because my commits all reference the issue number that relates to the change.
Every project I work on has a technical-decisions.org file. Also a daily-notes.org file with every failed experiment, test, install command, etc. The top level headings are dates.
Technical decisions used to be in the daily-notes.org file, but keeping in a separate file makes it more accessible to LLMs. I actually started that practice before LLMs were in common use, I struggle to remember why.
this is why in 2023 i started livestreaming whenever I work at my PC. I also take these kinds of daily and project notes, but it's a bit tedious and can take you out of the flow. so I just let youtube capture everything I'm doing and if I need to go back and remind myself of something (or ask an LLM a question about my livestream history, in the not too distant future) it's all right there.
We just recently started using ADRs (Architectural Decision Records). They are deliberately stored (in markdown) in the same repository as the source code for our SaaS business lives. If we can recover the source, chances are high that we can also recover the "why's". If we cannot do that, we are screwed anyways.
This. I encouraged my team to use a templated (standardized) ADR for any big decisions that don’t have an obvious answer or complete consensus and it had reduced the second guessing and relitigation of decisions to nearly zero. It also gave is a good snapshot of where we were when we made that call so historic decisions weren’t disparaged.
A few months from now, I'd love to have written down decisions for my current project:
- Why did I decided to use Kysely over Drizzle, Knex, Prisma, TypeORM or other ORM/SQL tool?
- How am I going to do migrations?
- Why am I using one of Deno/Bun over sticking to nodejs?
- Why did I structure the project as a directory per feature over controllers/models/services directories?
- Why did I fork this library and what are the steps to keep this thing updated? Do I plan to upstream my changes? Is there a GitHub issue or PR about it?
- Why am I hosting in one of AWS/GCP/Azure? Why not lambda functions? Why docker?
- Why did I pick this specific distribution of kubernetes over the other also lightweight alternatives?
- Why did I even start this project and what do I aim to accomplish with it?
So I created a # Decisions section in README.md
This way I don't keep doubting my own decisions and wasting time opening 20 documentation tabs to compare solutions yet again.