Set your data free with model-based architecture diagramming¶
Description
Diagrams are an excellent tool for documenting the architecture of our software systems: they’re information dense and they utilize the visual circuits of our brains to create effective learning experiences. Many of us create or update such diagrams regularly; there have been many talks on this topic at this conference over the years.
As great as diagrams can be, they have some downsides. In particular, they tend to lock up massive amounts of rich and crucial information into a format that can’t be reused in any other context. Because the information is locked up, it tends to be duplicated in various places in various formats and it takes significant effort to keep those duplicative datasets in sync.
I’ve recently come to believe that there’s a better way: modeling. If we model our systems in data, and make that data accessible, we are creating a single centralized source of truth for what systems, datastores, datasets, services, and people (roles) we have, and how they relate to each other.
There are many uses for that dataset; it’s not just a model, it’s also a catalog, or registry, of what is there even — a catalog that many people across an org need, and will be motivated to keep up to date. For example, anyone tasked with data governance needs to know what datastores and datasets exist, and who and what interacts with them. Security auditors need similar information.
Diagrams are another of the many uses of that dataset, and our diagrams can be greatly improved by being based on models of our systems. Multiple diagrams (“views”) can include the same elements of the model, but those elements are defined only once, in the model. If we change an element, we can quickly and easily re-render all the diagrams that include that element.
I’ll describe various benefits of documenting software architecture as data and share how I’ve been doing so, and describe my plans for improving the tools and approach. I’ll show lots of examples and try to wrap it all up at the end with an enthusiastic yet gentle call to action.
- Conference: Write the Docs Portland
- Year: 2020
