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

21–30 of 71 posts

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

#21

Post by nonameiguess »

ADRs are the only way I've ever seen it done well for a sufficiently large enough project, let alone something like an entire product line or suite of many projects. Sometimes those span multiple organizations. Think of the Internet and the IETF RFCs. Yes, they don't give a complete picture. Implementations may not match the specification. I don't really agree they require maintenance. It's just you have to write up a new one any time you change a decision and give a reason why. Yes, it takes a lot of organizational discipline to do that. You probably can't be in panic mode and it won't work for a startup that needs to ship in five weeks or they can't make payroll. But there isn't really a substitute for discipline.

As maligned as it can be, the single best organization I've ever been a part of for code archaeology, on a huge multi-decade project that spanned many different companies and agencies of the government, simply made diligent use of the full Atlassian suite. Bitbucket, Jira, Confluence, Fish Eye, and Crucible all had the integrations turned on. Commits and PRs had a Jira ticket number in them. Follow that link to the original story, epic, whatever the hell it was, and that had further links to ADRs with peer review comments. I don't know that I ever really had to ask a question. Just find a line of interest and follow a bunch of links and you've got years of history on exactly what a whole bunch of different people (not just the one who committed code) were thinking and why they made the decisions they made.

I've always thought about the tradeoffs involved. They were waterfall. They didn't deliver fast. Their major customers were constantly trying to replace them with cheaper, more agile alternatives. But competitors could never match the strict non-functional requirements for security, reliability, and performance, and non-tolerence of regressions, so it never happened and they've had a several decades monopoly in what they do because of it.

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

#22

Post by lwhsiao »

> Every solution requires someone to manually write something. Nobody does.

Hot take: hire people that value writing. Create a culture around that.

Oxide is a great example of a company culture that values writing, as shown by their rigorous and prolific RFDs: https://rfd.shared.oxide.computer/rfd/0001

See also: https://oxide-and-friends.transistor.fm/episodes/rfds-the-ba...

Many of these RFDs have hit HN by themselves.

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

#23

Post by mb7733 »

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…

Overall I agree with the approach, but just wondering, why do the first point if you are already doing the last two?

> * 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

To me the noise at the start of every message is unnecessary, and given a lot of interfaces only display 80 chars of the message by default, it's not negligible.

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

#25

Post by hakunin »

Simple: ask "why" in a PR review, put the answer in a code comment. If there is a bigger / higher level "why", add it to git commit description. This way it's auto-maintained with code, or stays frozen at a point in time in a git commit.

More: https://max.engineer/reasons-to-leave-comment

Much more: https://max.engineer/maintainable-code

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

#26

Post by hammadfauz »

mb7733 wrote: post #23
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…

Overall I agree with the approach, but just wondering, why do the first point if you are already doing the last two? > * 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 To me the noise at the start of every message is unnecessary, and given a lot of interfaces on…

If the pattern is consistent, it gets easier to ignore the noise when you don't need it. Like, a three/four digit number or a 3 letters and 3 numbers separated by a hyphen.

Sometimes, an issue might depend on another issue and contain commits from the other branch. Tagging each commit makes it easier to pinpoint the exact reason for that change.

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

#27

Post by hermitcrab »

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 decisions to write down why they made them:

* they may see it as reducing their career security

* they may see it as opening them up to potential prosecution

* it takes a lot of time

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

#29

Post by zain__t »

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 in one click. The incentive problem flips instead of asking someone to document themselves, you're just asking them to approve something already written. Much lower friction. Curious from your 25 years on this do you think the passive capture angle addresses the incentive problem or does the resistance run deeper than just the writing effort?

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

#30

Post by physicles »

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 go find the info, and then update the docs. No one else remembers what it's like to not know the things they know. And new hires don't yet know that "nobody writes anything" at your company.

In general, like another poster said, docs must live as close as possible to the code. LLMs are fantastic at keeping docs up to date, but only if they're in a place that they'll look. If you have a monorepo, put the docs in a docs/ folder and mention it in CLAUDE.md.

ADRs (architecture decision records) aren't meant to be maintained, are they? They're basically RFCs, a tool for communication of a proposal and a discussion. If someone writes a nontrivial proposal in a slack thread, say "I won't read this until it's in an ADR."

IMHO, PRs and commits are a pretty terrible place to bury this stuff. How would you search through them, dump all commit descriptions longer than 10 words into a giant .md and ask an LLM? No, you shouldn't rely on commits to tell you the "why" for anything larger in scope than that particular commit.

It's not magic, but I maintain a rude Q&A document that basically has answers to all the big questions. Often the questions were asked by someone else at the company, but sometimes they're to remind myself ("Why Kafka?" is one I keep revisiting because I want to ditch Kafka so badly, but it's not easy to replace for our use case). But I enjoy writing. I'm not sure this process scales.

Post reply on HN