Thanks for this comment. It is important to consider everything you said. CQRS is part of this book, but it is more of an explanation and might help you at some point (but does not need to). I think that's the main problem of CQRS - it is not understood well.
Throughout the book, I describe many concepts. Sometimes, I give some recommendations, and sometimes, no.
I accept your note—these four steps of evolution help you find yourself in one of them. Simplicity can be solved in multiple different ways; it is just the direction of keeping the solution as simple as possible (sometimes it will be more complicated, and sometimes less).
Enjoy reading it; if you don't like it, you can always return it within 60 days (Leanpub policy).
Thank you! This would not have been possible without stopping almost all other work.
This is my tip: if you want to write a book, plan unpaid holidays, or stop all consulting/freelancing work. Then, it is not that hard to keep up the tempo - when you know what you are writing about, of course ;)
I have similar observations, and over the years, I kept looking for something that would stand the test of time. I still remember horrors related to documenting architecture in Word documents (and requirements in Excel, omg).
The architecture decision log usually works well for the teams I work with. It is kept up to date and ordered thanks to architecture decision records.
I describe it extensively in one of the book's chapters with a practical example. I also show how to document alternatives considered when the record was added, where to keep it in case of mono repo, multiple repos etc.
I partially agree with you- nothing is better than working on "your own" mistakes, but some mistakes often repeat in software architecture. Why not take advantage and not repeat them by learning from others' mistakes? :)
Thanks for the tip! The book describes the approach that helps prevent my mistakes, and in each "step," I add several warnings and information sections about what to do and what not. I will try to think of how to add a better demo.
I tried to keep writing daily—sometimes for just 4 hours, sometimes for 13. On average, it was more than 8 hours a day, with some longer (1-week) breaks in between.
I will write another post on writing experience in the next few weeks :)
Thanks for your input - the evolution of the architecture is the apple of my eye. The demo part of the book comes from the evolutionary architecture step, which is described on around 100 pages.
Each architecture decision record should be added after the decision of the entire team. Then one folk can be assigned to add the ADR to the repo. It will work fine even if you do feature branches (battle-tested but you need to keep you branches short). In case of trunk-based development, there is no problem multiple feature branches.
The idea of ADR is to be immutable. Having multiple, ordered ADRs that touch e.g. the database works similarly to event sourcing - you have the entire history of all changes that were done within the context.
If you want to keep the entire history with changes in a single file called "database", then that's fine but the most important thing is to keep the history of decisions.
Having a single file with only the last decision is not the optimal idea as you lose the entire history.
YYMMDD is also a cool idea! I used it in one of previous projects.
What I don't like in your proposal are initials - since 2020 I worked in the environments where all folks were invited in making architectural decisions (that's the way I always try to push as an architect), therefore it would make no sense to add any initials :)
In case of monorepo where there are several independent deployment units, separating it via dir is quite simple solution. Additionally, if you move the code to some other provider, you move it together with the code (what is not guaranteed with e.g. GH issues).
However, I don't say NO. It all depends on context, if you decide to use issues - go ahead. I am a fan of pragmatism - do what you need in your context, don't blindly follow the rules
First answer: if you don't have any ADR yet, start with documenting the first decision that comes - don't go back in time to record 2 YO decisions.
Second: I described it as "Considered alternatives". There are 2 schools. One that puts it in "Decision" and the second one that puts it in "Considered alternatives " :)
I wouldn't document decisions that were not made as a separate ADR - it would be a mess after some time.
In recent years, I have encountered many problems in IT companies caused by incorrect software architecture. What do I mean by incorrect? In most cases, this is one direction – either it is too trivial or incredibly complicated in relation to the problem it is supposed to solve. Both cases lead to performance problems and stop the organization from being agile.