Comment by hu3 | Hacker News Reader

Comment by hu3 | Hacker News Reader

Parent Full thread

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.

What do you use for archiving github issues?

you could just call the github API

I've tried a couple of things. I wrote a tool for exporting them to SQLite: https://github.com/dogsheep/github-to-sqlite

I've also tried a mechanism where I have GitHub Actions write them out as JSON files in the repo itself, then I can git clone them in one go: https://gist.github.com/simonw/0f906759afd17af7ba39a0979027a... and https://github.com/simonw/fetch-github-issues

Til Github deletes your account randomly! Happened to a friend of mine recently, and he didn't get any explanation or recourse.

Of course, you have a relatively high profile, so could probably avoid it/get it reversed.

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.

> I struggle to remember why.

Should that "why" be in technical-decisions.org or daily-notes.org?

It should have been the first entry in some project's technical-decisions.org file!

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.

Could you share the template you're using?

There is an open community proposed standard template for ADRs, but I don't have the link

You also have to document alternative worlflows for your business while you don't get everything back to normal.

Lots of things can keep going with pen and paper or some cloud software.

At the very least, you have to communicate with your clients.

Reply on news.ycombinator.com