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.
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.
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.
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?
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.
Here’s a link to Harmel-Laws’post if anyone's interested: https://martinfowler.com/articles/scaling-architecture-conve...