I don’t think “instead” is the correct word here. “As well” I think fits better.

ARCHITECTURE.md will have the current state of the architecture. ADRs is the log of decisions that got you there. Both are very useful.

We have those pointless documents used by architects at my place of work, most of them have something on the lines of,

Micro services, Kafka, Kubernetes, because what if we have a billion users compared to the current 4k users.

GraphDB, what if SQL would not be enough

ElasticSearch, what if we have to do full text search along with stats.

But most of these documents are just short for any of these, "I want to try this new architecture/technology because it's fun, my colleague at a FAANG uses it, I've read the BOOK, and it looks good on my CV".

When they jump to design the next Big project, we have to deal with their decision, having twice as many services than our team, having to keep all the above mentioned DBs and technologies in sync which is of course a simpler problem than making those "big architecture decisions".

Sorry for the rant :(

Uh, sounds like these documents are the opposite of pointless, and are in fact working exactly as intended.

depends on the likelihood of those "what if" questions.

A bif chunk of good architecture is judgement: navigating the path between "building for the future" and YAGNI. It's much easier to end up at one end or the other, for example:

* k8s and microservices and sharded, cached data storage and Angular and NX in case we get to internet scale.... on our internal web app with max 400 users

* we're not gonna use a database because we don't know we'll need one... on an accounting system that needs to handle 1000s payments per hour.

I've seen both. I read GP's post as: we have ADRs that justify paying the complexity task when the balance of probability/evidence doesn't justify it. Good judgement is hard. It's one area where good devs/architects can make a really meaningful impact.

I was being a bit of a prick with my comment, I could've written it more clearly. Sorry for that. My point is this: what do you think is likely to happen if the requirement to write these documents is removed? a) In the absence of an impetus to justify architectural decisions, people cease creating overengineered architectures. b) People with an inclination to overengineer systems continue to do so, without documenting their reasoning. If (a) is plausible, maybe the documents are indeed pointless (or worse). I'm arguing that (b) is far more likely, and it's a strictly worse state of affairs than one in which decision records are written.

thanks for the reply and agree with it. Understanding the "why" - and "why not" - is very valuable. Those are the best code comments at any level of abstraction.

More concretely, if I was asked to consider rearchitecting a service that documented that it "used elastic search just incase full text search was needed" and that requirement never materialized, I'd feel much more comfortable dropping ES than if I was going in blind.