[farkin88]

Solid advice on clarity and editing. The only gap is what happens after the doc is approved? Without upkeep it decays into "design archaeology." A few years ago, Andrew Harmel-Law wrote about an interesting approach to scaling architecture conversationally, which includes lightweight Architecture Decision Records (ADRs) as one tool that could help here. ADRs live beside the code (adr/001-use-postgres.md) and capture context, decision, and status in a format short enough to, I think, revisit in every PR and easy to supersede when reality changes so the original rationale stays searchable months later.

Here’s a link to Harmel-Laws’post if anyone's interested: https://martinfowler.com/articles/scaling-architecture-conve...

[gerdesj]

I'm going to have to read that MF.com link fully and properly but I can't help but notice this:

"That’s it. That’s the Advice Process in its entirety." (speak to everyone involved).

Presumably anyone with the term Managing as a prefix in their job title is expected to glaze over at roughly this point.

Then we get to the meat: "The four supporting Elements". So I try to find out about ADRs:

I follow the first link:

https://www.thoughtworks.com/radar/techniques/lightweight-ar...

and eventually end up with this beauty (big download button at the bottom of the page from above):

https://www.thoughtworks.com/content/dam/thoughtworks/docume...

Would you mind pointing us at an actual definition of ADRs, please?

[farkin88]

There are so many external links, it's easy to get lost in this article. Look under content for the section titled "1. A Thinking and Recording Tool: Decision Records." It's under "The Four Supporting Elements." Here's a direct link if it's easier https://martinfowler.com/articles/scaling-architecture-conve... (Just search on that page for "The Four Supporting Elements)

There Harmel-Law defines ADRs as "lightweight documents, frequently stored in source code repositories alongside the artefacts they describe." He also provides a handy "Elements of an ADR" table. Let me know if you're still having problems finding it.

[gerdesj]

Thank you for the links. Sorry for the delay.

I do like to wrap up ... eventually! 8)

[commandersaki]

This is the case with Session messenger. It's been so many design and architectural changes that there's no single place that is authoritative of how it operates and works.

Btw use Signal if you want secure messaging, full stop.

[closeparen]

Then do Security, Privacy, Compliance, and the review committees of all affected orgs become blocking reviewers on any PR that touches an ADR? Are these PRs getting merged in less than 90 days?

[farkin88]

Fair point about process bloat. Just to clarify: I'm not an ADR expert nor do I personally know Harmel-Law. Just deriving insights from his blog post that I linked to earlier because I thought it was interesting.

But, I think you might be picturing ADRs as heavier than they need to be. Most changes seem like routine updates ("We decided Postgres" → "We're migrating to Aurora") that go through normal code review. The big architectural shifts that would trigger Security/Compliance review probably should anyway, ADR or not.

The key insight is that ADRs document decisions, they don't create them. If a change is big enough to need committee review, it likely needs that scrutiny regardless of whether there's documentation.

The alternative, undocumented drift, often creates much longer delays when people rediscover decisions during incidents. Curious to hear from folks who've actually implemented this at scale, though.