Architecture decisions made in meetings disappear faster than the ones written in PRs
Posted by Separate_Hospital701@reddit | ExperiencedDevs | View on Reddit | 74 comments
A decision that goes into a PR description survives. A decision made verbally in a Zoom and captured in someone's personal notes doesn't. Six months later someone asks why we built it this way and the person who remembers is whoever happened to write it down and still has those notes. The verbal decisions are where most of the real reasoning lives and they're the first to go. How are teams actually handling this?
Scary_Oil4570@reddit
Use talat.app to transcribe every meeting, then hook up the MCP to get it to claude to create tickets or whatever else needed, with all the context about who said what.
melancholyjaques@reddit
Write ADRs and commit them to source control
ninetofivedev@reddit
I've found that it's how you can tell if a manager is technical or not.
If they're not technical, they'll have you maybe document it in confluence or some shit.
Drives me nuts. I've even had other engineers who complain that I put documentation in Git and it should live in confluence.
One day they'll see it my way.
wxtrails@reddit
I didn't care where it lives as long as it's recorded somewhere. I can put a Confluence link in the repo.
The challenging part is getting people to agree and write it down.
EkoChamberKryptonite@reddit
I don't think being technical has anything to do with it. It largely depends on what the org uses and prefers for centralisation of documentation. Using git is well and good for Software engineers but you have to understand that some of your audience may not be technical so you must accommodate them as well. I've had orgs use git, Notion and Confluence. It depends on whatever works for your org.
hummus_k@reddit
Agreed. Discoverability is one of the most important factors in deciding where to store documentation.
EkoChamberKryptonite@reddit
100%.
Dro-Darsha@reddit
I write technical documentation in markdown files and the CI pipeline syncs it to confluence. Everyone happy.
ninetofivedev@reddit
It’s funny, I tried this exact thing but of course atlassian has the worst markup possible and it just ends up looking like shit.
Dro-Darsha@reddit
I forked
markdown-confluenceand adjusted it a bit for my purposes. It supports the Obsidian markdown flavor, including mermaid, which is almost good enough for my purposes. I added better support for complex tablesninetofivedev@reddit
That makes sense.
Sunstorm84@reddit
Worlds worst?
Salesforce exists.
Dro-Darsha@reddit
it's fine, actually. the pipeline isn't that much maintenance, mostly making sure to update the token every year. while confluence itself could be better, I get the best of both worlds. docs live with code that they are about, but I can still have everything in one place with full-text search, and it is usually faster to find the latest info there than in the respective repo
Empanatacion@reddit
The image in my head of technical docs in confluence is the final scene in Raiders of the Lost Ark, when they put the Ark in a crate and store it in a giant warehouse never to be seen again.
Confluence is a landfill disguised as a knowledge base. Every technical document is stored somewhere in the digits of pi.
ninetofivedev@reddit
100%. The only way to find something in confluence is to know exactly what you’re looking for. It’s absolute garbage software.
Empanatacion@reddit
I have, however, gotten a lot of mileage out of plugging mcp's into confluence and jira and having the AI wade through the muck for me.
It has sometimes noticed different documents contradicting one another (the worst thing about the landfill)and could tell me which was more recent when it asked me to clarify.
ninetofivedev@reddit
I’ve done the same, and it works. I’ll say it’s expensive. Using anything atlassian with Opus easily adds an additional $50-60 in token burn.
likeittight_@reddit
Document it in miro 😅😂
lenswipe@reddit
absolutely the fuck not. I put everything I can into git.
I recently wrote a 30 page report for church with a proposal for a new sound system. I wrote it in LaTeX for a bunch of reasons but one of the big ones was the fact that I could version it with git
FilterBubbles@reddit
Anyone have a good ADR format/process they can refer me to?
PmMeCuteDogsThanks_@reddit
but that takes effort and leadership skills
Zeragamba@reddit
might be one of the better uses for LLMs, as long as you verify that what it writes aligns with the actual decisions made
urko_crust@reddit
I feel like LLMs finally afford me the space to actually make sure stuff is properly documented
TheWrightStripes@reddit
Adr.md
lenswipe@reddit
this
nemeci@reddit
Also link to the ADR in file doc block.
Windyvale@reddit
Seriously how is this not obvious lol
alt_acc2020@reddit
I find this to be an issue with (very) senior SWEs and PMs who are better at talking about work than actually working.
A scoping document that needs to be signed off on by all the people who are working on the project or have any type of discretionary oversight alleviates it a fair bit.
foonek@reddit
I'm definitely better at talking about work than working. Is that necessarily a bad thing though? I think we as an industry need to learn to think things through before jumping in head first
Left-Echidna8330@reddit
My personnal take (and please take no offense) is that people who are all about talking without the skill are not adequate for architecture decisions. Sure, thinking before coding is important, but being a good coder is essential when it comes to archituring anything.
I have a few people like that in my org, no code all talk, I’ll be honest, I have a low opinion of them and I second guess everything they say. From my point of view, they got where they are because of their people skill, not technical skill.
foonek@reddit
I mean, yeah. It's not that I never code, but sitting and coding is kind of boring to me, so I can't focus on it as well as I can on the architectural part. I've done a lot of it in the past, but recently it just doesn't go as well as it used to.
No offense taken, don't worry
caboosetp@reddit
I think the implication is that their baseline for working is bad.
If you've got solid work skills and you also happen to be better at talking, you are fine.
psyyduck@reddit
It's hard to make decisions without data. Frequently I have to actually implement something and see how it works (eg in OP's PR) then backtrack if necessary. Chatting on zoom is not a substitute.
termd@reddit
We write down architectural decisions in design docs.
Not in the doc and not signed off on, you do it at your own peril. If it works no one will say boo to you, but if it doesn't, doom is coming your way.
ikkiho@reddit
The mechanism is more specific than "write things down." A decision survives if and only if it reaches people who weren't in the room, and it reaches them because the storage medium is searchable from the place they're already working.
ADRs in source control work for that reason, not because they're "written documents." They sit next to the code, show up in
git log, get linked from PR descriptions, and the next person who modifies that subsystem trips over them naturally. Confluence and Notion decision registers fail at the same teams not because the writing is worse but because nobody navigates back to a separate tool to find them. The path from "I'm modifying this file" to "what was decided about this" needs to be one click, not three plus a search.The honest reason most ADR programs collapse: the cost of writing is upfront and the benefit is deferred by 6+ months, when a different person is debugging it. So you need a forcing function. The two I've seen actually work:
(1) PR template requires a link to a decision record for any change that touches a specific list of architectural seams (not all PRs, just the ones that move boundaries). Tied to a CI check on the PR description.
(2) A staff or principal eng who refuses to approve PRs without a written rationale and is senior enough that the friction sticks. This is the cheapest version but it doesn't survive that person leaving.
A useful diagnostic: if the same decision keeps getting "made" in three different meetings six weeks apart, the problem isn't that people are forgetting, it's that no forcing function exists and the implicit decision was actually unstable. Writing it down would have surfaced that earlier.
The counterintuitive part is that shorter, more frequent meetings make this worse. Context never compounds. The notes from one 90-minute architecture session retain more than the notes from six 15-minute ones, because the longer session forces participants to actually surface the disagreement.
BoBoBearDev@reddit
Can everyone one explain how often you need to document those architectural design? Because in my case, we just make bunch of dumbass CRUD web services. And same with frontend, the same dumbass react components.
Yes, there are parts of the system we do have design documents. It is rare for us. Most of the time we just yet another cookie cutter cooy and paste dumbass components/microservices.
caboosetp@reddit
Probably 2-3 times a month. Most of our services aren't CRUD though.
BoBoBearDev@reddit
What kind of services are yours?
Leading_Yoghurt_5323@reddit
yeah meetings are where context is born and also where it dies 😅 teams fixing this usually pipe decisions straight into docs/ADRs right after .
james__jam@reddit
Sounds like no one is accountable for the architecture. Otherwise, somebody would have been chewed off for having the final architecture not the same as the agreed upon.
symbiatch@reddit
By writing the decisions in the tickets, or elsewhere. That’s it. Simple. Just start doing it.
ArrivesWithaBeverage@reddit
This. “Per meeting/discussion on…”
AssaultLemming_@reddit
Write actual solution architecture documents and require solution architectures to be approved by an architecture review board...
ninetofivedev@reddit
Absolutely gross. As soon as my company thinks they need an ARB, I'm gone. Nothing like a bunch of assholes with self-inflated egos arguing about branching strategy and naming standards, meanwhile picturing themselves designing rockets for NASA.
Scottz0rz@reddit
ARB imo doesn't necessrily just mean snobby asshats whose roles are solely being "Solution Architect" or "Systems Architect" groups who oversee and make all the decisions and proposals must be anointed by them to be approved before coding work begins.
I always dealt with fairly chill ones at small-mid size companies where you're just asking some Staff+ Engineers who volunteer to regularly give advice and review architecture diagrams in a weekly/biweekly meeting with people or answer questions in an #architecture-forum slack channel basically.
If you're building something normal, low-to-mid risk that uses your existing stack, you're by no means obligated to talk to them if you feel pretty good. Y'know, a CRUD Spring Boot app with a MySQL database and some Kafka connectors isn't going to upset anyone if that is your stack.
If you need to build something different that hasn't really been built before... it depends? Is it going to affect other teams meaningfully? Is it a potentially important new service that might become shared ownership? Do you not really know what to call it because naming things is hard and they're sticky and you're not sure what long-term visions might be?
Maybe it is a fairly simple thing but this is your first time doing something because you're either new to the company or trying to get promoted and are tech lead on a thing suddenly.
ARB definitely is a term that has some negative connotation and legacy enterprise baggage, but the high level idea of "A group of volunteer Staff+ Engineers across the company who are willing to help you if needed" is the type I've encountered more often than not.
ninetofivedev@reddit
Yeah and agile doesn’t mean scrum and communism doesn’t mean corruption.
Except it almost always does.
Scottz0rz@reddit
Good faith line of questioning, not arguing. Wall of text because this is actually a genuine line of questioning for my personal growth.
I'm fairly new to my current company and am a Senior aspiring to be Staff, generally speaking. I know the definition of both varies wildly from company-to-company because titles are made up.
Out of curiosity, what are the organic checks that have worked for you typically?
Project coordination is sometimes (usually) a shit show thus far and it depends on the project, but there are some dogshit designs coming through where, to me, if I proposed this arch in my DDD or system design interview when I got hired, I might not have gotten the job.
I'm talking like... a single business domain that could've been 1 microservice with a relational database that instead is like 4 microservices each with a MongoDB/DynamoDB table and making changes means you have to coordinate 2-3 deployments potentially.
There are a lot of legacy services that are solid "Do Not Touch" fragile that were written 4-10 years ago when the company was far more startuppy.
The company currently does not have a formal arch review process. It did at one point in the distant past, seemingly after they were burned a few too many times, but it was abandoned again in favor of velocity because they felt it slowed them down too much to add overhead.
But really, the much more important point is this:
This is solid "it depends" and is rather complex and deeply political because at most companies "you are responsible for your decisions," architecturally speaking falls to the wayside when you are far more accountable for delivering features on-time that "work" and if they blow up and don't scale 1, 2, 3, 5 years later, well... there's maybe a few issues:
New use cases pop up all the time and features evolve over time
Maybe the original design did work reasonably well at first, but the use case evolved over time. What was originally a random one-off feature suddenly became a core part of the app after 5 years.
A basic example of making an assumption of an arbitrary decision 10 years ago that there'd be a 1:1 to mapping of entities and suddenly some random product director / VP is saying:
What does "held responsible" mean?
The person may have quit, been fired, laid off, or got hit by a bus. The code is still there running in prod. How do you hold them accountable after that?
Code and service ownership regularly changes hands if the company is big enough and re-orgs happen all the time. Even if the service was perfectly fine originally like I said, it might get hot potatoed or shared around and people have different opinions on "fine" for their use case they want out the door quickly that goes unnoticed until it finally drops in the hand of some poor sucker who has to confront tech debt after 5 years because the thing constantly goes down and explodes and no one really knows how it works.
It's impossible to be perfect when it comes to knowing future use cases and scaling concerns as a company grows, but enforcing a good starting point and laying a good foundation helps avoid pitfalls for the next person later on.
SalamiJack@reddit
If you don’t have a basic architecture design document and review process your team is making slop. I 100% guarantee it.
ninetofivedev@reddit
We just have individuals who own things and everyone else stays in their fucking lane.
If we need to work together, we do it organically, not through some bullshit profess with anointed individuals who think they’re elected officials on behalf of their engineering constituents. They’re not. They’re just engineers 1-10 at the org and they’re the only 3 who are still left.
SalamiJack@reddit
I don’t know where you’re getting this weird elected officials bit…your review board should be your team, made up of contextual key reviewers who are POCs of the areas you’re touching, with some form of rotating bar raiser between your tech leads. That’s it. For changes that are internal or very encapsulated, the process isn’t required. For changes that touch multiple systems or are high in risk or complexity, they should be required.
ninetofivedev@reddit
Review boards aren’t ever teams. Teams typically have no problem coming to decisions within their own frameworks.
My point wasn’t that they’re elected. My point is they view themselves as leaders serving their constituents, like elected officials would.
Anyway, ARBs, like i mentioned are almost always a handful of people who have themselves the title “architect”, they sit atop their ivory towers and they do the easiest part of the job. The find gripes and they soapbox their preferences while trying to convince everyone that it’s actually an objective truth and not just their preference.
We can agree to disagree at this point. Ensure your Saturday.
Wonderful-Habit-139@reddit
That person is not the Lord of slop operations for no reason.
Jokes aside, I think their claim could be different depending on how they document the design. If it is similar to how open source does it, with proper sections in the documentation for developers and another one for users of the API/program/whatever, then it doesn't sound too bad.
If it's just the usual .md files that are generated by LLMs as a planning step, then yeah it's slop.
pixelboots@reddit
Decision register in Confluence.
morphosis7@reddit
This is how we do it. The person championing the issue writes up a document in the decision log, describing the problem space, options considered, the benefits / drawbacks of each, and a proposed decision. Others impacted are tagged in the document (and the document is announced in the project Slack channel).
There's a window for comment and feedback, which is captured at the bottom of the document with a Gradients of Agreement scale (5 = full agreement, 4 = agree with noted reservations, 3 = abstain / no impact, 2 = non-blocking disagreement, 1 = veto for noted reasons).
This far, the projects I've been on have never seen a veto used in this process - we tend to talk everything out prior to proposing the decision, and if it turns out that a better option is out there, this discussion process has surfaced it - so the author updates to decision document accordingly.
This works well when you're dealing with colleagues who aren't on GitHub, so an ADR isn't an option. That brings project sponsors, project managers, UX folks, and any other non-engineers into the process (plus those groups are also using this same workflow for their own work, so we get tagged in their relevant decisions as well).
F1B3R0PT1C@reddit
Get transcript of meeting. Turn transcript into notes. Turn notes into ADR. Publish it as a document in company knowledge portal. If your company doesn’t have a knowledge portal, then just let it ride because they’re not going to survive long term.
Kuresov@reddit
Why isn’t the decision recorded in the document? That’s what it’s for.
Great_Cut_207@reddit
how do adrs compare to just documenting in a wiki
kagato87@reddit
The person driving the meeting (usually the team lead) takes the notes directly in an epic, then after the meeting spends the time to create all the child tickets. If it's a smaller task it might be a regular ticket instead of an epic, but the key is the notes are taken directly in the same jira that will go through the whole point/estimate/schedule process.
When planning comes around if any child tickets are still too big they might get split up, though that's usually more for branching than actual ticket separation.
MoreRespectForQA@reddit
With AI transcriptions which also share all of the off color jokes I'd also prefer were lost to the ether.
Hot-Profession4091@reddit
This is why you have an agent create a summary document. Also, commit all meeting notes to the repo for context for other agents. It’s like having them sit in on all your meetings so they have the same context people have.
New-Locksmith-126@reddit
If you need to go to a secondary document to explain why you made a decision it was probably a bad decision to begin with.
Document your code and your systems, of course. But "decision records" are really only useful to understand which moron decided to build this crap.
The "decision" is usually something like:
"The Pipelines team already had Replication Manifests on their roadmap, and Bill is planning on refactoring our Response Manager in Q4, so we decided that the new Reflux Marshalling service should be bumped up to align with sales' Revenue Marshalling priority.
Therefor we decided to write it in Haskell because Bill said he liked it that one time"
LaintalAy@reddit
MoM - Minutes of Meetings What was discussed, decided and by whom.
These MoM decisions may then be written in a detail design document or similar or just referenced.
Where to place these doesn’t matter. It could be a word file, a confluence or a Gitlab Wiki page… as long as the team knows where to find this information and is more or less organised.
Bemteb@reddit
You don't need these notes to remember what was decided, you are smart and remember of course. You need them when in a few months someone asks "wtf, why did you do it like that, we never wanted it that way!" you can answer with a simple "Yes." and the link.
Just need to frame it correctly and suddenly people will love writing detailed minutes.
boring_pants@reddit
You know you can write things down even if they originate in a meeting, right?
Bonus points if you write it down and commit it to git. Then you have the PR description and commit comments and the documentation exists side by side with the actual code.
chrisrrawr@reddit
6 months? try 2 weeks
roger_ducky@reddit
I’ve found only documentation that stayed with the source control actually had an effect long term.
Either that or it all becomes “ask Bob.”
nonades@reddit
My skip level showed me something he does.
My company has a very tough time making important decisions (it's exactly as dumb as it sounds). When my skip joined, he got extremely annoyed with the lack of decisions and some people would conveniently not remember
So now he's got a folder of CYA documents where he'll share his screen with a doc open detailing the important items that were agreed on, and then go around the call collecting names of who all agrees to what was decided. Now if people try to backtrack, he has that document
CowBoyDanIndie@reddit
I have stopped and tried to encourage my coworkers to stop having design discussions on teams with management. Management hasn’t worked in the domain in a decade but has a phd in the domain (multiple I think) and questions and second guesses every decision, weighs in and changes the design in ways that don’t make sense, then it all gets ignored cause it doesn’t work and we just do what actually works instead. Detailed design up front never works exactly and always gets some changes in implementation. Things work much better explaining the change in the PR and explaining how it was tested and verified.
I should mention that I work in a very researchy cutting edge domain (robotics perception). It’s very easy to come up with designs that look flawless and would even work flawlessly in simulation but fall apart completely in real world testing. 10 years ago I worked in a different domain and followed the opposite approach which was right at the time, but trying to follow that kind of process now just wastes time.
nkondratyk93@reddit
PR description turns the decision into an artifact - someone can comment on it, disagree with it, link back to it six months later. a Zoom decision has none of that. the fix is usually just making the artifact mandatory: ADR in the PR description. decision gets accountability when it has a location.PR description turns the decision into an artifact - someone can comment on it, disagree with it, link back to it six months later. a Zoom decision has none of that. the fix is usually just making the artifact mandatory: ADR in the PR description. decision gets accountability when it has a location.
zugzwangister@reddit
If it isn't in writing, it didn't happen.
ConspicuousPineapple@reddit
If you don't have somebody writing it down live in the task description during the meeting you simply suck at meetings.
mpanase@reddit
You can even reflect it in official docs.
The very first time one of the limitations detailed in the docs makes itself evident, you will learn that a ton of people didn't understand yet pushed to get their choice in.
haskell_rules@reddit
Follow a design process that requires written requirements and design documents, formal approval of those documents with signatures of peer reviewers, with QA that validates the process was followed before release into production.
davvblack@reddit
ugh yeah this one is tough and we don't do it right either. we try to capture as many arch decisions in ERDs before development, but decisions downstream of mid-project discoveries don't really make it anywhere