How to make great ADR decisions without slowing down

Development Architecture
1

When presenting OEP-56: Architectural Advisory Process to engineers, especially as it relates to ADRs, a common reaction is the belief that soliciting feedback would unnecessarily slow down the process. The unspoken conclusion is that soliciting feedback should be avoided.

What are ways we could dispel these fears? Here are some thoughts:

  1. I think an ADR doesn’t need to have a deadline for accepting/responding to feedback. Someone can merge an accepted ADR as soon as they believe they have made a good decision. This should not block new feedback from coming in and/or the ability to iterate on the decision. I’m not sure if others agree, and I don’t think this is codified. See next point.
  2. Related, I think it is ok to change an accepted ADR that has merged if the dust is still settling on the decision. The more correct approach might be to use the “Provisional” status until it is ready to be “Accepted”. However, in many cases, this just causes process overhead and a psychological feeling of a slower process. I’d call this “Accepted until proven otherwise”.
  3. Documenting potential short responses to feedback could help people understand how to avoid length time-consuming conversations defending what they still believe is a good decision. For example, “Interesting point, but we’ll agree to disagree” or “Thanks, but I still like the current decision. I’ll list your idea under Rejected Alternatives” or “Thanks. That is an interesting future idea if anyone wants to pick that up.” The point is, people know that differing opinions have the potential to eat up a lot of time, and we want them instead to know that this can be avoided.
  4. The benefit to everyone of soliciting feedback, is when your response to a comment is something like: “Wow. Great point. I’ll update the decision.” This opportunity is what we don’t want to miss out on, so I want to help people get the best of all worlds.
  5. If we do all of this, I hope we can increase motivation for people to actively solicit feedback where appropriate. If you no longer fear feedback slowing you down, will you be more open to finding those comment-gems? See Arch Coordination - How to announce for examples of actively soliciting feedback.

I’m not sure if the results of this discussion would result in small updates to OEP-56, and/or a new separate how-to that includes the sales pitch and recommendations.

3 Likes
2

I like these ideas. I’ve actually always wondered what status to put on ADRs and agree provisional status is pointless. It’s checked in and part of the repo or it’s checked in and marked “actually we decided not to do this go see this other ADR” right at the top and that’s about it. Or it’s been updated because we weren’t perfect the first time - it’s not like we would magically know when we can change the status from provisional to perfect.

A How-To doc feels like the right venue to me.

3

I like the idea of disagreeing (“We’ll agree to disagree”, “I’ll put your idea in Rejected Alternatives”). I think there’s huge benefit to the second statement - having a bunch of Rejected Alternatives is awesome and hugely helpful if your implementation starts to go south.

One social thing that can come up is many people find it hard to leave a disagreement alone, or assert that they are right (especially when power dynamics come into play, such as a more senior engineer asserting an opinion that the more junior author disagrees with). I am not sure how to combat this, I mostly want to raise visibility about those attitudes and dynamics that can make moving on despite a disagreement difficult to do.

BUT: often times, it is really important to just move forward rather than make a discussion linger forever. Good to capture disagreements somewhere in the ADR, or even in a GitHub issue if it’s a thing that needs considering in the future.

4

You’re right, I couldn’t find this codified anywhere. But not having at least an announced period for comments, however short, would be counter productive. It can even be a way to indicate urgency, thus speeding up the process. If the period is, say, 24 hours, it would be clear to the pinged stakeholders that they need to react sooner rather than later. Maybe we can add this to the sales pitch? (That said, hopefully decisions that impact a comparatively large number of stakeholders will have longer timeframes.)

Whatever the case, not having a period for comments potentially gets us back to ADRs being created not only after the decision was made, but after related code has already been committed to master, thus mooting the “wow, great point” scenario. I believe getting away from this is one of the main motivations of OEP-56.

I agree we should be able to change an ADR after it’s been accepted… as long as there’s a changelog in the ADR itself, and that the new PR gets the same OEP-56 treatment as during the ADR’s inception.

As for “Provisional” vs “Accepted”, I figure it’s just an indication of whether there’s still time to avoid rework. Maybe the decision is applied to an isolated component while it’s provisional, and if everything works out and no objections are made, the rest of the codebase is updated. We should definitely make something like this clear, though.

And to get back to the kernel of this discussion:

I’m curious: what does that process currently look like?

Unless we’re talking about a one-man project, I imagine impactful architectural changes are shopped around internally, and that takes a certain amount of time. That time presumably increases with the number of internal stakeholders. If you have geographically distributed teams, even more so. And so on.

My point is: would moving the discussion into a public forum make it so much worse? Maybe most decisions made internally go unchallenged, or are usually solved in a single sit-down with everybody, but I suspect that’s not the case. Or is the problem making it asynchronous?

To be perfectly honest, I have a nagging suspicion people are more resistant to the public bit than the perceived potential slowdown. But let’s tackle one thing at a time. :slight_smile:

5

@ashultz @sarina @arbrandes: Thank you for sharing your great thoughts. I’m sorry I didn’t acknowledge your responses earlier. This has been on my backlog for a while. I added some additional thoughts.

Ok. We’ll see where we end up.

I’ve had cases where it made sense to me to use Provisional (for some reason) as the author. However, if you as the author feel it is pointless for a given ADR, I want you to feel free to call it Accepted.

@sarina: You add some great points on handling disagreements on an ADR. I am also trying to solve for cases where an ADR never gets created in the first place, or long after the fact, because they feel these imagined disagreements will slow them down. I mostly want people to know that they can move quickly, and don’t need to get everyone to agree.

Agreed that 24 hours seems like a reasonable short period, when a short period is needed. I also agree that all of this is about seeing if we can get people to write and share ADRs earlier and earlier in the process.

Introducing a changelog for the rare ADRs that are updated sounds like a great idea. I personally think it is fine if it doesn’t exist on the first version. I’ve often wondered how to clarify cases where an ADR is partially superseded, and a changelog would certainly help support these types of updates.

You may be right, but I’m not sure what this means and if they really are different things. Or, maybe people don’t feel being slowed down, as much as the emotional experience of having to publicly reject other peoples’ ideas? Feel free to provide more details.

1 Like