Here are the problems with this thing:

> The most important ingredient of ESADs is the intent of the author. ESADs generally do not happen organically. ESADs are the product of expertise, clear intentions, and specific goals.

Have you ever met an architect that had expertise, clear intentions, and specific goals? I haven't. They usually ask you things like "is your application stateful?" and then check a box for yes/no. Product owner maybe a little bit more likely, but still usually no.

> ESADs, in contrast, are created to be documentation. They are meant to be valuable in their own right and aren’t tied to a larger work like an article or presentation. Furthermore, they are intended to provide long-term value. ESADs are designed to be clear, precise, and comprehensive.

Documentation isn't necessarily clear, precise, and comprehensive. Documentation is a whole lot of things. And when you're designing architecture, you need a lot of different visualizations and representations of the system in different forms. User context, stakeholder context, data context, legal context, transaction context, availability context, operational context.

I like their idea of 'perspectives', as it can relate to the above different representations. But to get more and more detail, eventually you have to read the code, and at that point you should just point someone at the code, rather than try to shove it all into a diagram that nobody's going to maintain. If you're really lucky, someone will have made a system to turn the code into diagrams.

> Finally, ESADs should include inline notes for the sake of comprehensiveness. These notes help explain, in prose, things the perspectives themselves cannot. A two- to three-sentence summary for each perspective is ideal

But you might need tons and tons of notes to understand what you're looking at. A couple sentences isn't going to provide comprehensive, precise understanding of what you're looking at. But documentation, and architectural decision records, will. But if you include snippets of that in this other document, now you have documentation sprawl that won't be updated. Maybe you can provide URLs to the documentation as these snippets.

> Do not use drag-and-drop diagramming tools for creating ESADs.

Oh, so it can be super annoying and time-consuming to design your diagrams/architecture, great.

> Furthermore, diagrams created with drag-and-drop tools generally cannot be diff’d or merged.

They can if you support export to a diffable format!

> Ilograph defines diagrams using YAML

We're gonna capture all that multi-level highly-precise documentation in YAML? And how are you supposed to edit that - by hand in a text editor? You should never edit YAML by hand. If you have a tool to do the editing, you don't need to use YAML, which is both functionally limiting, and misleads users into thinking they should edit it by hand.

user:	throwaway277360
created:	November 3, 2021
karma:	1