My mental model always formed much more around what kind of data flows and interactions happen between components.
As a big fan of Domain Driven Design I found "domain storytelling" a useful technique when adapted to software systems.
With these diagrams it was much easier to convey complex systems and their temporal couplings. Especially to higher Management as they can actually "read" how the sequence of events flow.
Try it out and see if it can be another tool on your belt.
I really like this approach - thanks for sharing! It's much easier to follow a Domain Storytelling diagram than the current technical flowcharts we use for domain documentation and visualisation at work.
> This is why you want to limit the amount of information to process to the most relevant ones, to make the most relevant thing easy to transfer.
This is the limitation of a single image diagram. Anything worth diagramming has some complexity; which means you have to remove critical info or risk it becoming confusingly messy.
> A widespread mistake is to mix abstraction levels inside a diagram. This really increases the cognitive load.
This is one of the core ideas behind https://terrastruct.com [0]. Split complex diagrams into digestible pieces, via levels of abstraction.
[0] full disclosure, i made it out of frustration at current diagramming tools.
I’ve long played with this idea. I would like to draw at the most detailed level and then let the tool generate the different levels of abstractions for me.
Yeah we're working on reducing the time it takes to generate. Eg hooking up to databases to get schemas, source code for dependency graphs, using text to minimally express.
But, I'll say that I think however long it takes, diagrams used for documentation is looked at much more than the author will have spent on it, and the benefits of having a mental model be clearly shared makes it worth a lot of effort.
Good read. I’ve always enjoyed using C4, it’s nice to have consistent notation across diagrams. Another decent tool is C4Builder [1] if you like PlantUML. It’s based on Docsify.
> Each connection should have a label.
It’s amazing to me how often you see diagrams without labels on connections.
[lambda] -> [s3]
“Lambda arrows s3?” Is it reading, writing? Creating buckets? Managing the ACL? That arrow between two really common components leaves a LOT to the imagination.
This is valuable, with the addition that the quality of architectural thinking could be elevated in most of the organizations I've been in if before they put marker to whiteboard if they adopted the principle of symmetry.
If you don't start with symmetry, you lose meaning because you are representing relationships with a basic inconsistency. I've sat in meetings with very senior architects who say, "I'm not an artist, but here's my thinking," and then go on to ramble and sound out their own parenthetical ideas while everyone is too polite or embarrassed to interrupt.
Start with dots and lines that make simple polygons or trees, or multigraphs. Use solid lines for direct relationships, and dotted ones for abstractions and conditionals, and arrows for the direction when you know it.
Literally every single visual idea you are expressing reduces to a graph, and starting with symmetry in your drawing provides free clarity about the relationships between ideas.
Arguably, maybe you don't want that clarity of symmetry because you want others to feel like it's not decided and they can use the uncertainty of your foggy thinking to contribute their interpretations, and the difference between collaboration diagrams and explanatory ones is probably in this, but as a boss of mine said to me once, "I don't care what you do, so long as it looks like you did it on purpose."
There’s definitely a market to take in this area since ms visio has basically fallen out of fashion. I’m using miro at the moment but it really falls short in terms of predefined shapes and pictos.
I'd be really interested to hear which icons you're missing. I'm actually just about to push an update that will add a few more icons to the library (i.e. queues, caches, DNS etc). Expect those over the next few hours. Will try to include any suggestions in the next release. Thanks for checking it out!
you can basically take inspirations (aka steal) from what ms visio offered. I haven't used it in a long time, but FWIR the picto & shape library was completely insane. Every single technical fields was there.
To help spread some insights, could you go into a little detail about why?
I recall a friend of mine once saying his planned product would have a price-point that a typical mid-level exec could simply charge to their company credit card without being an eyelid. It looks like the isoflow prices are in that sort of range. I've always wondered if that model works (my friend went a different direction in the end).
Depends on the company. Processes vary, but for my former corporate employer, to give you an example, giving someone money in exchange for SaaS software needs 1) Vendor assessment 2) IT Risk Assessment 3) Privacy Assessment 4) Information Security Assessment 5) Proving ROI to budgeting people and getting their approval 6) Purchase order to a cost center.
Thanks for this, I suspected similar. Only yesterday I was thinking about the payment processes I've experienced in universities and councils in the UK. Every month would see a flurry of emails with invoices, purchase orders and cost centres flying around. Absolutely horrific.
Other then that, as the article mentions, it all depends on the audience and their background/knowledge level. Why not gather Feedback from those your diagrams are intended for?
I love the book ‘Back of the Napkin’. He talks about identifying what you are trying to present, and marrying that to the diagram you draw. I’ve used those approaches many times in tech/product descriptions.
10 years in the industry and i've never needed any diagrams other than the ones that my IDE can automatically generate from the code and configuration itself. Anything else is an exercise in futility and serves only control-freak managers.
This is an indicator that you have either worked on systems that were not very complex, or work in an environment where cross-team collaboration is not necessary.
I won’t question your claim about your personal need, but if you believe such diagrams only serve control freak managers, you are closing your mind to the many other possible reasons that diagrams need to exist.
This is anecdotal (so is your claim), but I have aphantasia - I cannot see with my mind. Diagrams are one of the only ways I can reason about some things that I cannot otherwise visualize in my head.
People communicate, conceptualize and learn in different ways, and that has nothing to do with control-freak managers.
> Diagrams are one of the only ways I can reason about some things that I cannot otherwise visualize in my head
It’s very similar with me.
When I’m grasping a new concept I spontaneously get a pen and paper and start drawing block diagrams to visual cause/effects, sequence of events/actions etc. Also when I’m trying to recall a concept, I have to draw a block diagram.
Same when I’m explaining it to someone. I have to draw, otherwise I lose my chain of thought within a couple of sentences.
Not sure if you're only ever worked alone, but there's an awful lot of value to teams in being able to collectively review designs before committing to them, which you can't do if you have to code everything up just to generate the design. There's also the fact that, in a lot of enterprise and government environments, a design needs to be approved before you can implement it, so you need a way of expressing a design that doesn't require you to implement it first. This isn't approval by managers, but by the customers and owners of the environment you're going to be installing software into.
Of course, once you have an implementation, documenting the as-built configuration using automated tools that generate from your actual code and runtime system is the way to go.
I wonder if this is a natural problem of the code not being a 1 on 1 reflection of the proposed model (or a superset which includes the proposed model), as well negligence in not syncing them up when something changes, which isn't a problem with code (just generate it again).
Often, the thing worse than no mental model, is an inconsistent mental model sending you in the wrong direction.
As a big fan of Domain Driven Design I found "domain storytelling" a useful technique when adapted to software systems.
With these diagrams it was much easier to convey complex systems and their temporal couplings. Especially to higher Management as they can actually "read" how the sequence of events flow.
Try it out and see if it can be another tool on your belt.
===
https://domainstorytelling.org