Beyond Whiteboarding: Creating Expert System Architecture Diagrams
blog.ilograph.com
blog.ilograph.com
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.
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.
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
Yes. Humble Startup Bundle is a startup waiting to be started and explode.
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 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.