This appears to be an idealistic proposal that is presented as if it is an accepted standard.
It talks about Expert System Architecture Diagrams (ESADs) as if they are an existing thing. I googled that term, however, and guess what? The only place "Expert System Architecture Diagrams" is found is in this blog post or references to it.
Furthermore, it quotes a "prime directive" of ESADs, "When creating expert system architecture diagrams, always strive to truly inform your viewer rather than merely make an impression," but I can't find a source for that quote anywhere, except as a paraphrase of a 2020 post on the same blog.
A lot of the idealism is accompanied by hubris. The post turns up its nose at whiteboard diagrams hastily put together by filthy casuals using their actual hands. And it implies that unless you're constructing your system diagrams in YAML, they don't qualify as expert-level.
If you're really interested in creating useful diagrams for system architecture, there is a host of material out there that is more established and authoritative. Information design is the relevant broader discipline, but there are many sub-disciplines that pertain specifically to the visual representation of the design of software systems.
It's nothing to do with expert systems. Whoever wrote it decided to reuse an well-established existing term for their own purposes.
The title ran a bell in my head, though. In the mid 1980s, to demonstrate Personal Consultant Plus, a commercial EMYCIN clone developed by Texas Instruments, to potential customers, I developed an expert system with it called CAFES - short for Choosing Architectures for Expert Systems. This was based on a technical report of the same name by Paul Kline and Steven Dolins. There's a citation on the web https://apps.dtic.mil/docs/citations/ADA163343 but unfortunately it isn't available in PDF.
I suspect the reading is intended to be “expert (system diagrams)”, not “(expert system) diagrams”, but I felt the same confusion as you when I saw the title.
"Casual" whiteboard-style diagrams are of course fine in many (really most) situations. My intent was not to look down on them or anything. This is an appeal to think about what going beyond "casual" diagrams and towards documentary diagrams looks like and requires.
Yay, 13USD x team size to keep a simple architecture diagram up to date. Enterprises are rich, I get it, but tools like this should cost max 0.50USD/user/month. Or even better, someone should bundle several tens of these kind of tools and sell them for a single enterprise license. Effectively that is what M$ is doing of course, it offers all of github/devops/azure in a single subscription, so that is what I get to use.
Even though I might prefer pivotal tracker or zenhub, codecov, readthedocs or whatever, no way I am going through the hassle of getting all these 5-15/USD/user/month services paid for one by one. But if they were all bundled in a single subscription I might reconsider
I think that'd be hard to navigate, as far as negotiating with the services you're re-selling. For one thing, they're services, not one-off purchases, so it requires an ongoing relationship. For another, lots of these companies' paths to profitability (well, actually selling out to a BigCo, but whatever) hinges on "owning" the user to steer them into future products, or, for the ones that aren't doing that, they'd have to fear getting edged out by other bundled services applying that tactic against their product.
These fail my litmus test, which is, "can a third-party look at the diagram and make sense of it without verbal explanation?" For a more formal approach to coherent diagrams and white boarding, I recommend the C4 model. It's conceptually simple and results in better system documentation than the free form method that's commonly used.
Learning the language of understanding charts and diagrams is not obvious. From reading maps to understanding log-log plots, box and violin plots, etc. I mean there is a whole industry around this.
I think the ability to be able to transition in the same diagram to different semantic complexity levels is amazing. I want this for ALL of my communication and information mediums.
I am only commenting on the tools ability to zoom in and out from an abstraction level and not on the philosophy of how diagrams are constructed.
I made a diagram like this for a test automation system inside the firewall that talks to cloud providers. Using Graphviz (DOT), it was challenging to depict the system faithfully without a maze of lines from nodes on one side of the graph to the other.
I agree with the sentiment of defining a graph in code, but I really wanted to give it a nudge from time to time, like swap these two nodes so the arrows don't cross. I'm only an occasional user, so maybe there are ways to do it.
On a related note, I would like to have arch diagrams checked in to a GitHub repo. I remember there is a Java application that does this well, but it's a Java application and I don't want to spin up a 2GB container only to generate some diagrams...
But what does the YAML look like? If it's a specific YAML format that is only supported by this commercial tool then it's no more universal than github action's yaml is.
> 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.
It talks about Expert System Architecture Diagrams (ESADs) as if they are an existing thing. I googled that term, however, and guess what? The only place "Expert System Architecture Diagrams" is found is in this blog post or references to it.
Furthermore, it quotes a "prime directive" of ESADs, "When creating expert system architecture diagrams, always strive to truly inform your viewer rather than merely make an impression," but I can't find a source for that quote anywhere, except as a paraphrase of a 2020 post on the same blog.
A lot of the idealism is accompanied by hubris. The post turns up its nose at whiteboard diagrams hastily put together by filthy casuals using their actual hands. And it implies that unless you're constructing your system diagrams in YAML, they don't qualify as expert-level.
If you're really interested in creating useful diagrams for system architecture, there is a host of material out there that is more established and authoritative. Information design is the relevant broader discipline, but there are many sub-disciplines that pertain specifically to the visual representation of the design of software systems.