this post was submitted on 05 Jul 2023
27 points (100.0% liked)

Experienced Devs

4007 readers
13 users here now

A community for discussion amongst professional software developers.

Posts should be relevant to those well into their careers.

For those looking to break into the industry, are hustling for their first job, or have just started their career and are looking for advice, check out:

founded 2 years ago
MODERATORS
snowe
jmk1ng
drewsiferr
27
Documenting Architecture Decisions (cognitect.com)
submitted 1 year ago* (last edited 1 year ago) by canpolat to c/experienced_devs
17 comments fedilink hide all child comments
 

I wonder if there are others using ADRs for documenting their decisions.

you are viewing a single comment's thread
view the rest of the comments
[–] mark 2 points 1 year ago (1 children)

we generally first discuss the topic and then write the accepted decision in an ADR. So, there isn’t much room for discussion/voting afterwards.

This makes sense. I guess it would cut down on the noise in the PR since, at the point of its creation, it's already been accepted. Our repos have so many other teams contributing to them that it's hard to rally everyone to build consensus on an ADR beforehand. I guess we could hold meetings, but having feedback in a PR allows us to go back and look at what discussions led to a decision later on.

How does your team build consensus before opening the PR? Is it through slack or some other chat tool? Or maybe a meeting?

[–] canpolat 2 points 1 year ago (1 children)

We do that in a meeting. In some cases it may take several meetings before we can make a decision. But I think those are generally fruitful meetings (I don't see them as waste of time). PRs give people a chance to think about these on their own pace, but when it comes to decision making, I feel like meetings actually save time (provided that people are sufficiently informed).

It's also possible that our ADRs deal with higher level decisions and is therefore easier to establish some sort of a consensus. From your description (especially the "refactoring" bit) I thought maybe you are using ADRs at a level that is closer to code. I cannot really think of our ADRs stopping people from refactoring the code in any way :)

[–] mark 3 points 1 year ago

The meetings approach is interesting. I think we did those for RFCs but I remember they were very very long and unproductive. I think the company size matters when determining the right approach.