Cryptic comments left in the code.
How do you capture WHY engineering decisions were made, not just what?
41–50 of 71 posts
Re: How do you capture WHY engineering decisions were made, not just what?
#42Put the ADR in the PR as a requirement. Then automate extracting the decision info into an actual ADR.
But that's still after the decision was made... I guess it's still useful. But maybe that person didn't actually weigh a decision and tradeoffs when they made the change.
Re: How do you capture WHY engineering decisions were made, not just what?
#43> Why Redis over in-memory cache?
Sometimes the answer to "why?" is that the dev had a hammer and the codebase was starting to look an awful lot like a nail. In-memory cache isn't considered as a serious option nearly enough imho.
Re: How do you capture WHY engineering decisions were made, not just what?
#44I built an agentic framework that distills ADRs from Teams meetings where everyone discusses freely. Works surprisingly well to record the WHY without someone having to do the job.
Do people discuss detail on Teams in your company? In my place it turns into calls..
Re: How do you capture WHY engineering decisions were made, not just what?
#45I can't say ADRs work that great, in my experience, but the flaw was more connecting them to other architectural stuff to make them actually discoverable and drawing the boundaries in a logical way (what goes into an ADR and what goes into a living design doc?).
"Not maintained" seems kinda weird to me, because at least as I see an ADR, it's like a point in time decision right? "In this situation, we looked at these options, and chose this for these reasons". You don't go back and update it. If you're making a big change, you make a new ADR with your new reasons.
One place I worked did have an interesting idea of basically forcing (not quite) the new hires to take notes on all their onboarding questions/answers as they went and then sticking it in the company docs. It at least meant that incorrect onboarding docs got fixed quickly. Sometimes you had good reasons for stuff, sometimes the reason is "dunno, that's just what we do and it seems hard to change".
Re: How do you capture WHY engineering decisions were made, not just what?
#46step one: have you ever heard of a guy named Aristotle
Re: How do you capture WHY engineering decisions were made, not just what?
#47My masters thesis is wrt to scaffolding ADRs. I draw a fine line between required human input and what's safe to scaffold. There's a lot of tooling which I'll omit most details but involves recursively scaffolding/pruning and maintenance over time.
Re: How do you capture WHY engineering decisions were made, not just what?
#48My masters thesis is wrt to scaffolding ADRs. I draw a fine line between required human input and what's safe to scaffold. There's a lot of tooling which I'll omit most details but involves recursively scaffolding/pruning and maintenance over time.
I have a ton of papers to read wrt making decisions, human-ai interaction, ADRs, etc if you're interested.
Re: How do you capture WHY engineering decisions were made, not just what?
#49Your company is missing an architect role. An architect would know why redis over in-memory cache and have that pattern documented. They would definitely know why graphql for the one service but REST everywhere else - they would have it documented from design approval meetings.
Re: How do you capture WHY engineering decisions were made, not just what?
#50Did he write down everything he learned? That way the next person only needs to cover the intervening time period.
Conceivably LLMs might be good at answering questions from an unorganized mass of timestamped documents/tickets/chat logs. All the stuff that exists anyway without any extra continuous effort required to curate it - I think that's key.