Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How do you capture WHY engineering decisions were made, not just what?

news.ycombinator.com

Post reply on HN
Print view View original

51–60 of 71 posts

Re: How do you capture WHY engineering decisions were made, not just what?

#51

Post by 4star3star »

hammadfauz wrote: post #19

If you do these things: * File issues in a project tracker (Github, jira, asana, etc) * Use the issue id at the start of every commit message for that issue * Use a single branch per issue, whose name also starts with the issue id * Use a single PR to merge that branch and close the issue * Don't squash merge PRs You can use `git blame` to get the why. git blame, gives you the change set and the commit message. Use t…

This seems reasonable to me. Devs and BAs flesh out business processes and ultimately document decisions in our Jira issue comments. When you have an issue id handy, it's not that hard to go read what the rationale was for a feature.

I have been ignoring Jira's AI summary, but I suppose that could be useful if the comments were very long.

Re: How do you capture WHY engineering decisions were made, not just what?

#53

Post by 4star3star »

sdeframond wrote: post #16

Sometime the best way to why a (Chesterton's) fence is blocking the road is... to remove it and see what happens! Sorry, not really an answer to your problem. But I feel you, this is a genuinely hard problem. Keep in mind that, pretty often, the reason something is the way it is comes down to "no real reason", "that seemed easier at the time" or "we didnt know better". At least if you don't work on critical systems.

As a counter point, it may be quite subtle and hard to notice what goes wrong when you remove something to see what happens. Imagine you see a large sql query that has a bit of logic that doesn't make sense to you. If you go change it without knowing why it was that way, and users keep on using report output from that query, who is going to notice when they get 982 records in their report instead of 983 one day? It's easy to spot when erroneous data APPEARS, but it's a lot harder to notice when valid data DISAPPEARS. Oh, they really did have a good reason to use outer apply instead of cross apply, there. Oops.

Re: How do you capture WHY engineering decisions were made, not just what?

#54

Post by mentalgear »

Keep the reasoning as close to the code as possible.

1. Code should be self-explanatory, so should vars, function names and the entire shape be.

2. For the remaining non-obvious bigger design decisions, add a comment header (eg jsdoc) above the main section code block, and possibly refactor it out into its own file. Prefer to have a large comment header (and possibly some inline comments) outlining an important architectural part than having that knowledge dissipate with time, separate external docs and your leaving workers.

Re: How do you capture WHY engineering decisions were made, not just what?

#55

Post by hysan »

(Don’t take this as advice. Just writing my own experience with this.)

This is the reason why I take the time to summarize all “why” decisions and implementation tradeoffs being made in my (too lengthy) PR descriptions with links, etc. I’ve gotten into the habit of using to collapse everything because I’ve gotten feedback multiple times that no one reads my walls of text. However, I still write it (with short s now) because I’ve lost track of the number of times I’ve been able to search my PRs and quickly answer mine or someone’s “why” question. I do it mostly for me because I find it invaluable as I prefer writing shit down instead of relying on my flaky memory. People are forgetful and people come and go. What doesn’t disappear is documentation tied to code commits (well… unless you nuke your repo).

Re: How do you capture WHY engineering decisions were made, not just what?

#56

Post by iSnow »

4b11b4 wrote: post #39
iSnow wrote: post #36

I 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.

Sounds pretty cool. Is this published?

No, b/c I did so on company time. And it's old industry, they wouldn't open-source it.

But it took ~2 weeks with the help of Claude, so relatively easy to replicate.

Re: How do you capture WHY engineering decisions were made, not just what?

#57

Post by iSnow »

gardenhedge wrote: post #44
iSnow wrote: post #36

I 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..

Teams calls. I let Teams transcribe it and parse the transcription via AI.

Re: How do you capture WHY engineering decisions were made, not just what?

#58

Post by physicles »

zain__t wrote: post #32
physicles wrote: post #30

First, recognize that, for the first time ever, having good docs actually pays dividends. LLMs love reading docs and they're fantastic at keeping them up to date. Just don't go overboard, and don't duplicate anything that can be easily grepped from the codebase. Second, for #3, it's a new hire's job to make sure the docs are useful for new hires. Whenever they hit friction because the docs are missing or wrong, they…

The Q&A doc you're maintaining is fascinating you've essentially hand-built the thing I'm trying to automate. The 'Why Kafka?' entry is exactly the kind of decision that disappears when you leave. The search problem you raised is the core of what I'm solving — not dumping commits into a .md, but extracting structured decisions from the conversation that surrounded the commit: the Slack debate, the PR review, the tick…

If I leave, the Q&A doc probably never gets updated again.

We're in the process of trying to get as much stuff as possible into source control (we use google docs a lot, so we'll set up one way replication for our ADRs and stuff from there to git). That way, as LLM models get better, whatever doc gets materialized from those bits and pieces will also automatically get better.

Re: How do you capture WHY engineering decisions were made, not just what?

#59

Post by al_borland »

4b11b4 wrote: post #38
al_borland wrote: post #33

If it’s something in the code, that’s where I use comments. It’s the only place people have a chance of seeing it. Even when I add these comments some people ask me about the code instead of reading them. This isn’t just for others, I forget as well. Something to the effect of… # This previously used ${old-solution}, but has moved to ${new-solution} because ${reason} Or # This is ugly and doesn’t make sense, but ${cl…

Putting decision inside the code is interesting... but scattered. Some decisions are made way higher up and implicitly touch many places

Yeah, this doesn’t solve the “why Redis” problem. What I’m most concerned about with this is stopping someone who might be trying to update the code in the future (including me) from going down a rabbit hole I’ve already been down.

Re: How do you capture WHY engineering decisions were made, not just what?

#60

Post by hermitcrab »

zain__t wrote: post #29
hermitcrab wrote: post #27

I worked on the problem of recording 'design rationale' ~25 years ago. It is a big problem. Particulalry for long-lived artefacts, such as nuclear reactors. Nobody is quite sure exactly why decisions were made, as the original designers have forgotten, retired or been run over by buses. And this makes changing things difficult and risky. The biggest problem is that there is no real incentive for the people making the…

This is incredibly valuable context thank you. The career security point especially is something I hadn't fully articulated but explains why ADRs always die. Nobody wants to document themselves out of a job. The approach I'm exploring tries to remove the human writing step entirely passively capturing decisions from PRs, Slack threads, and tickets and auto drafting the rationale. The human just approves or dismisses…

>The human just approves or dismisses in one click.

A busy engineer trying to hit a deadline is just going to do the easiest thing, aren't they?

Also there is all sorts of tacit knowledge that goes into a decision and I just don't think you are going to capture this automatically.

(I worked on it 25 years ago, rather than for 25 years.)

Post reply on HN