Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by dotancohen on Wednesday July 16, 2025 @08:22AM
(#44581433)
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.
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by sjs382 on Wednesday July 16, 2025 @09:09AM
(#44581939)
> I struggle to remember why.
Should that "why" be in technical-decisions.org or daily-notes.org?
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by dotancohen on Wednesday July 16, 2025 @10:05AM
(#44582551)
It should have been the first entry in some project's technical-decisions.org file!
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by qntmfred on Wednesday July 16, 2025 @09:46AM
(#44582350)
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.
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by MrGilbert on Wednesday July 16, 2025 @08:22AM
(#44581438)
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.
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by goopthink on Wednesday July 16, 2025 @08:35AM
(#44581575)
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.
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by Mossy9 on Wednesday July 16, 2025 @09:23AM
(#44582059)
Could you share the template you're using?
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by unixhero on Wednesday July 16, 2025 @05:58PM
(#44587245)
There is an open community proposed standard template for ADRs, but I don't have the link
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by simonw on Wednesday July 16, 2025 @09:56AM
(#44582444)
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.
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by nchmy on Wednesday July 16, 2025 @11:47AM
(#44583591)
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.
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by sitkack on Wednesday July 16, 2025 @11:36AM
(#44583465)
What do you use for archiving github issues?
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by tough on Wednesday July 16, 2025 @12:29PM
(#44584148)
you could just call the github API
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by simonw on Wednesday July 16, 2025 @01:50PM
(#44585030)
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
Re:Ukrainian hackers destroyed the IT infrastructure of Russ...
by forinti on Wednesday July 16, 2025 @12:47PM
(#44584360)
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.
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.