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

61–70 of 71 posts

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

#61

Post by al_borland »

zain__t wrote: post #34
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…

Those comment templates are actually really well structured you've invented a mini decision record format without calling it that. The problem you're hitting is discoverability the why is there, but only if you happen to read that exact line. What if a new dev could ask 'why does this auth flow work this way?' and your comment was part of the synthesized answer along with the PR, the Slack thread, and the ticket that…

Most people where I work use Confluence for the overarching architecture decisions, but that also has a massive discovery issue.

If there is a Confluence doc that relates to my code, I will usually cross reference it. The Confluence link goes at the top of the file, and a link to the repo goes into Confluence. Even with this, the discovery problem remains, as one of those things needs to be found.

Using chat is a non-starter, as our chats are purged after 6 or 12 months. PRs also seem like a very challenging place to keep the information without a lot of systems in place and strict adherence.

Tickets can work, until the ticketing system changes. I’ve been through 3 ITSM platform changes and 3 changes in agile software. Old information is lost in these transitions as it’s usually only in-flight stuff that migrates. Confluence will meet the same fate soon I’m sure.

At the end of the day, the code is the only thing I can trust to be there. Once the code is gone the information matters less. I also try to be pretty diligent about readme files can get pretty wordy. Adding some kind of architecture doc into the repo might be another option, similar to what claude.md has become for a lot of people. I actually might do this for a project I’m starting now, as it’s pretty confusing… though I’m hoping I can come up with a way to make it less confusing.

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

#62

Post by pxue »

we use a service called Briefhq.

First: It’s a MCP/cli you can hook up to Claude code and slack, it integrates with GitHub.

the harness lets you record decision as contextual info you can pull up whenever your start a planning session.

It also makes sure your decisions don’t conflict with each other.

I find myself talking through a decision I made months ago with it, update it with any new decisions and it just figures out how to merge everything.

No extra workflow outside of this.

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

#65

Post by hiyer »

lowenbjer wrote: post #15

My take after running engineering teams at multiple companies: documentation survives when it lives next to the code. File-level header comments explaining each component's purpose and role in the architecture. A good README tying it all together. If you compartmentalize architecture into folders, a README per folder. This works for humans, LLMs, and GitHub search alike. ADRs, Notion docs, and Confluence pages die be…

> documentation survives when it lives next to the code. 15+ years ago, this was pretty much the standard. Every decision - whether major or just a hack to handle a corner-case - used to be recorded in the code itself. Then tools like Jira and Confluence came in and these things moved to undiscoverable nooks and corners of the organization. AI search tools like Glean and Rovo have improved the discoverability, though I'd still prefer things to remain in the code.

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

#67

Post by sdeframond »

4star3star wrote: post #53
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…

That's a good point indeed.

For this particular case I like to put in a comment next to the weird thing that seems out of place. It can be a short summary and the link to a specific ticket for example.

Also, tests.

Edit: actually id like to emphasize the need for tests. One must be able to refactor code without fearing to break undocumented requirements.

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

#68

Post by 4b11b4 »

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

Earlier quoted context omitted.

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.

Yeah that's the point of being able to revisit past ADRs easily. Will have demo soon

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

#70

Post by lowenbjer »

zain__t wrote: post #17
lowenbjer wrote: post #15

My take after running engineering teams at multiple companies: documentation survives when it lives next to the code. File-level header comments explaining each component's purpose and role in the architecture. A good README tying it all together. If you compartmentalize architecture into folders, a README per folder. This works for humans, LLMs, and GitHub search alike. ADRs, Notion docs, and Confluence pages die be…

The git hook idea for enforcing doc updates is really interesting has that actually worked long term for your team or does it eventually get bypassed?

Check back in 2 years time, for now it has survived fine. Someone will be tuning it to write the documentation soon, instead of just blocking!

Jokes aside, i think LLMs will enable us to handle information in a much better and smoother way. We should use them!

Post reply on HN