As others have said the C4 model is a great way to address a number of these issues.<p>I can’t find the right video at the moment but Simon Brown (creator of C4) gives a great talk about creating his DSL, Structurizr, for C4, which he developed during COVID lockdown (if memory serves). There are many videos on YouTube of Simon talking about “C4 Models as Code” so I’m sure any one of those will suffice.<p>The focus is on creating the model of your system architecture, from which the diagrams you extract are a specific projection of that model. Rather than a diagram be the main artifact. It’s a simple but very powerful concept that I’m always surprised isn’t more widely used.<p>Structurizr models can also be exported to display as ilograph diagrams, mermaid diagrams and more.
Also very much worth a mention is icepanel, a lovely tool for architectural model that implements the C4 model heavily.<p>I saw Simon talk at a conference in Sydney about 10-15 years ago and heard about C4 for the first time in that talk, it’s been one of the most influential talks I’ve been to in my career as it made a lot of fuzzy things in my head all start to come together in a way that just made sense.<p><a href="https://c4model.com/" rel="nofollow">https://c4model.com/</a><p><a href="https://structurizr.com/" rel="nofollow">https://structurizr.com/</a><p><a href="https://www.ilograph.com/" rel="nofollow">https://www.ilograph.com/</a><p><a href="https://mermaid.js.org/" rel="nofollow">https://mermaid.js.org/</a><p><a href="https://icepanel.io/">https://icepanel.io/</a>
This reminds me of the following:<p>* Devs: We need a better language than Javascript as the lingua franca of the web!<p>* Users: Sure, use whatever language you want -- just make sure it compiles to Javascript, which is already the lingua franca of the web.<p>Keep in mind that the consumers of technical diagrams are often non-technical folks. And they don't care about how they get their diagrams. They just want to be able to understand, at a high level, what's going on in the black box.<p>You can either convince every single one of them that devs need to focus on better system design tools ... or you can continue to give them the diagrams they want, just using a smarter process to generate them.<p>Or you can treat them as entirely separate problems, because fundamentally system design tools are building tools, and system diagrams are communication tools. In most cases you can improve them independently.
It's not so hard to do static and tracing-based analysis to capture all the calls that various systems make between themselves. Similarly, it's not so hard to graph all of the metrics of a system.<p>That's not really all that useful. Diagrams, like other forms of documentation, are a <i>format</i> for communicating something to the reader. It means that they should spend more space on the important flows rather than the exceptional ones. They'll explain the meaningful parts of a sequence rather than just giving a series of function calls. The various tools we have for doing this (boxes showing what systems talk to what, sequence diagrams, database schema diagrams) provide a rich enough language for that communication.<p>Death star diagrams are bad because they spend a bunch of time and effort to convey one piece of information: "there are a lot of systems here" rather than anything actually useful for someone attempting to navigate a specific part of the system.
I think at least part of the problem is that todays "agile" methodologies lure people into almost completely neglecting analysis and design, as if these steps are forbidden in agile. So for many dev teams I have seen, agile basically means "we have no plan".
>Today, we have the technology and knowledge to create tools that prevent developers from wasting valuable development time deciphering static, outdated diagrams,<p>One issue is that diagrams in general are pretty universal. As long as your tool can makes shapes and connect them, you can use it for any kind of architecture. For example it will work flow charts for 50 year old Fortran to UML from the 90s to microservices diagrams from now and I bet to whatever is common 50 years from now.
Thank you everyone for reading my article! I’m the author, Thomas Johnson.
This article stems from my frustration with the typical approach of asking, “What diagramming tool should we use?” instead of addressing the root problem: the need for up-to-date, easily accessible system architecture information.
That’s why I co-founded Multiplayer. We focus on automating the creation and maintenance of system architecture diagrams and creating a single source of truth for system information. This includes your individual components, APIs, dependencies, and repositories.<p>We’re language and environment agnostic and you can start with a napkin sketch or a photo of your whiteboard. And this is just the start, we have many plans for how to evolve system design tooling including supporting popular integrations and models like C4.<p>It’s early days for us. I’d love to hear what you think: <a href="https://www.multiplayer.app/" rel="nofollow">https://www.multiplayer.app/</a> (It’s free!)
There is a potentially interesting standard many may not know - IEC 61499 - Standard for Distributed Automation, first ed 2005!!! and related to PLC type controllers.<p>It was meant to be the next step forward from IEC 61131 that described the five PLC control languages, but far ahead of it's time.<p>61499 introduced the concept of an executable specification, and went on develop tie ins with XML and OPC. The executable specification is a particularly interesting idea, effectively emerging as no code these days<p>But two decades on is still only starting to get traction, seemingly because it was so far ahead of it's time, and the target audience was potentially mostly only just branching out into software because they were now programming ladder logic, instead of designing panel boards with hundred of relays and timers.<p>But, it is worth a look for some ideas in the space, particularly the executable specification concept (you know this can only lead to a DSL of some kind), but also including their diagramming that looks a lot like UML but maybe works better, along with 4Diac software package, consideration of how some of the more esoteric aspects of OPC fit into all this, and more slightly obliquely, TLA+.
In 1971, M. Bryce and Associates marketed PRIDE, the first commercial software methodology for general business use. It was originally an entirely manual process using paper forms, but it was already far more comprehensive than anything called a "methodology" we use today. For example, in PRIDE, every artifact of the systems design and implementation process -- each high-level requirement, each software module, each database table and column, and more -- is assigned a tracking number and extensively documented as to its purpose in a unified knowledge repository. This was decades before Git or JIRA, and at first it was all done by hand, but not for long.<p>In the 80s, they marketed PRIDE/ASDM, which combines PRIDE with Automated Systems Design Methodology, a suite of system design tools written in COBOL for mainframes. Far from being mere diagramming tools, they assisted in all aspects of an information systems design from initial requirements down through coding and database management. A key component of ASDM was the Information Resource Manager (IRM), a searchable central database of all of the information artifacts described above along with their documentation. Another component was Automated Instructional Materials (AIM), the online documentation facility, which not only provided instructions on how to use the system, it also provided step-by-step directions (called "playscripts" in PRIDE-speak) for each member of the development team to follow, in order to see a business system through from abstract design down to software implementation and deployment. Provided the directions were followed, it was next to impossible to screw up a system or subsystem implemented through PRIDE/ASDM.<p>This level of comprehensiveness and clarity is <i>the</i> gold standard for business IS development. And it seems to be nearly lost to time.
I feel like <a href="https://plantuml.com/" rel="nofollow">https://plantuml.com/</a> gets close to what I want by being able to make diagrams with code, but for system design what I <i>really</i> want is to be able to have diagrams generated directly from the code itself, maybe with some extra comments/annotations that help it along.<p>Does anything like that exist already?
We have the tools and ways to express architecture. The problem is no one is bothering to actually learn it and do it well.<p>Everyone seems to look for answers involving not having to spend any time learning anything new.<p>UML, BPMN, 4+1 view, it can do it all. Just learn it and make sure everyone else in your team does too.
Google Slides and Drawings (under + > More...) are great tools. They support the diagramming objects, connectors, shared collaboration, and integration with the other Google Doc tools. They also have great history and diff tools as well as team comments, with actions.
I wonder if modeling/system design people didn't have new insights since the last 20 years (when Model Driven * started to sink).<p>Languages changed a bit, more types, more concurrency, more functional idioms. Yet I feel we're not going anywhere.
To take this a different way, Devs need AI-driven system design tools, not diagramming tools. The work to automate the process to define, code, deploy, and document tech/app solutions using GenAI is arguably well underway and the days of humans producing layers of boxes and arrows documentation is thankfully numbered.<p>More directly, the need for the special snowflakes and the ensuing complex system design processes will be reduced as we drive towards more automation N(A) frameworks.
If we had a complete and evolving set of requirements for any reasonably complex system, we wouldn't really read them once they no longer match the system we have delivered.<p>Systems and requirements go hand in hand but the reality is requirements are eventually codified, and after a point only the system matters because <i>the system</i> is the reality and the requirements were just the formal inspiration.<p>I would love to see automated requirement analysis and verification from code.
You need to use diagramming tools that are meant for complex systems. Almost all of the complaints in this article are caused be using generic drag-and-drop diagramming tools.
Also GUI design tools like the WinForms designer but for more modern toolkits please. VB/Delphi/WinForms were such a joy to design and XAMl (let alone web frontent) is such a pain to write.