And the ADR for using ADRs is there in ComposeUI/adr-001-use-adrs.md at main · morganstanley/ComposeUI (github.com)

If you are watching the new repo, you might have spotted that the first few PRs are about adding a set of “ADR”s, Architecture Decision Records.

So you could ask, why? You could ask the same question, why a project is using X instead of Y – actually a new person joining a team definitely going to ask the question, why you using Entity Framework and not NHibernate? And believe me, most likely you would hand wave and say “for historic reasons” because you would absolutely not remember anymore. And that’s generally very unfortunate.

Documentation. Yes, I’m also a developer, and I also hate writing documentation. Who doesn’t hate that? Actually, I think, above a given age, when you are being told ‘documentation’ you do have a particular picture in your mind, which is books and books of lot of pages, probably bound together using twines called project documentation while still using Rational Unified Process or Microsoft Solution Framework like I did? Or the other way around, yes, there are tons of documentation, scattered among different systems, hosted off the code, in wiki or something – gets outdated the day you write it, not part of the source control, not structured (or rarely), therefore, why to write it at all, again?

So, documentation, why hate it, but can it be done better? I don’t think I ever started to like writing documentation, believe me. But writing Architecture Decision Records, following a certain scheme in them and keeping them in the same git as my code – that’s more of my liking, believe me. So, just to summarize, an Architectural decision is a software choice. One that addresses either a functional or a non-functional (like project structure – or the fact you do write ADRs!) requirement that is architecturally significant – framework choices, programming languages you choose, OSes you target, data storage, communication patterns, persistence, validation, logging, telemetry; you just name it. Of course, you should not take the term “architecture” too seriously or interpret it too strongly. I mean, look at not-that-recent update of ThoughtWorks’s radar when talks about ADRs: Lightweight Architecture Decision Records | Technology Radar | ThoughtWorks – they went from ‘trial’ in 2016 and speaking about evolutionary architecture to a mainstream adopt in just a few years. And they also suggest to store them in version control instead of wiki/website. Let me finish it with the sentence from the Radar: “For most projects, we see no reason why you wouldn’t want to use this technique.” So, our http://github.com/MorganStanley/ComposeUI is not different 🙂