I use yEd for drawing this kind of thing. It allows me to make a horribble mess of boxes and arrows, then auto-cleans it up with a few clicks in the menu.
It requires making sone compromises, however: Box inside box does not always end well. It is a worthy tradeoff for me, as I can document things much faster, and you get a feel about what will or wont work after a few tries.
Is yEd free to use? The underlying yWorks SDK seems to cost 5 figures for one developer working on one web site. It must be very capable to have customers for ~20 years.
Their page states it is freely available. I cant seem to find the license on their website, unfortunately. I believe it started out as a demo for their paid library, but turned out to be a good standalone application.
It's weird that the Whimsical diagrams don't look... whimsical. I've started using the sketch style on my draw.io and sketchwow diagrams and that magically makes them more engaging somehow. I'm not sure where the difference comes from, but just clicking that checkbox results in comments about both the contents and the style. (Where otherwise I can't tell if anyone's even read them)
Instead of a "DO NOT ERASE" sign we have introduced a system where you can simply draw a lock icon somewhere on the whiteboard. Only few colleagues know about this arrangement, and even I myself often erase a lot of stuff before I spot that icon.
My company has a policy to erase all whiteboards on Friday nights. Nobody tries to steal whiteboard space from the next meetings, and there are no obsolete diagrams from 2018 around with a do not erase.
We use Miro and actually, for high-level stuff, ideation, etc it's pretty good as a tool using post-it notes. I don't go past mid-level stuff though, once you have your components and systems there are better tools for the job.
I really enjoyed this article. When I draw an architecture diagram, write documentation, code or really do anything at work I take a moment to try to make it look "nice". I can't explain why I do it, I just know when I look at it I like it more.
I've always been slightly concerned it was possibly not the best use of time, but I have never had anyone tell me not to do it.
What I like about the article is that it articulates, in a practical way, how to make something more beautiful, whereas I go by feel.
> Discussions gravitate around this diagram. People randomly walk up and stare at it. Questions are answered by pointing at it. Periodically throughout the day, chairs swivel around to face this centerpiece, their occupants folding their hands behind their heads.
I do this, too. Coding is actually a very visual endeavour for me. I can only describe it as "flow". If my code doesn't "flow", I'm not happy with it. I am baffled by my teammates who seem to have no visual awareness of their code. They might forego whitespace between the close of one function and the declaration of the next, or alternate between having one or more parameters per line in a function signature. It sticks out to me like a sore thumb, but they don't seem to care.
>I am baffled by my teammates who seem to have no visual awareness of their code.
I have somewhat avoided this because it can make you look like you're changing things for no good reason (no easily communicable reason, anyway).
I still do it when people have too much going on for a single line though (ternary ops + function calls + string/number formatting, etc which is very common in enterprise-y programs).
When I make network diagrams in Visio I feel the same way. I put my Steve Jobs hat on and obsess over some small detail. Yes, sometimes it is time consuming but it feels some kind of cup for me. I know I have some kind of technical artistic talent, in high school I wanted to be a drafter.
Even if you never share anything, just the thought process that goes into the ordering of the blocks and elements on the page force you to think about the larger structure and dependencies. It's incredibly helpful.
Taking the time to clean up a diagram usually means making it 'easier to comprehend.' Every time you use the clean diagram, you've saved time and energy with a reduced cognitive load.
I feel like diagrams should not be pretty. For example, colors should convey meaning rather than being aesthetic or artistic choices.
I get that ugly software diagrams are not fun to look at, but to me dressing them up is like adding curves to a line chart - yes it's visually appealing but it interferes with the data being conveyed.
Beauty is useful, but it needs to be the last step. When something like nice people also assume the contents have been polished and so since a lot of work went into thinking about it already it isn't worth the time to question if it is right. You can question if you understand it, but the diagram itself is right and so the problem is you.
Most diagrams have not had that must thought put into them. They should look a little ugly because that implies it might not be right so look for errors.
> They should look a little ugly because that implies it might not be right so look for errors.
Weirdly, prettiness is the bigger red flag for me wrt to error. I see that and feel like more attention was put into that than the underlying information.
Ugly, brutalistic, utilitarian stuff tends to imply a focus on correctness to me.
Nicely presented data can certainly inspire confidence, which might or might not be justified, but I think attractive presentation can be more than just a sales pitch. Ultimately, we create these visualisations to convey information to someone else, so good presentation should help that someone to navigate and understand that information, and it should avoid introducing unwanted bias or ambiguity.
If that means creating an overview of the system architecture for new team members that uses pretty colours and multiple fonts and icons and shaded boxes but that helps them to understand the system more quickly and correctly than an overwhelming page of black-and-white text and arrows, the extra styling has done its job.
You are confusing good and readable with beautiful. A pencil sketch can be readable and good, yet still look like it can be changed. By contrast if you make it look like perfect it will look like it cannot be changed.
Sorry, I don’t understand the point you’re trying to make here. Finding ways to present information that are both functional and attractive — and stay both of those things as the information evolves — can be a challenge, but I don’t believe those are completely independent axes and I don’t think achieving and sustaining both in combination is an unrealistic ideal. Indeed, I’ve spent a significant part of my professional life creating specialised user interfaces for various products that try to do exactly that.
The point is if something looks too polished people assume that polish is all the way. You look at a polished chart different from a sketch. If I show you a napkin sketch of some new idea I have you understand it is new and not well thought out, thus you ask is the big picture idea correct. If instead the same idea is well polished in full color you think the big picture is correct and start looking at details that might need some adjustment. Depending on what sort of feedback you want, you need different types of drawing.
This is true, and why some diagramming packages include "draft" modes that intentionally change the presentation to make it look less permanent/polished looking.
Had to take Color Theory to get my BFA. We learned things like the "speed" of colors: yellow is the "fastest" and purple is the "slowest". Only a little yellow is needed to balance out a lot of purple. Same for balancing the other colors. You use these balances for guiding the eye (lots of yellow on a purple field).
When you keep this in mind, diagrams or not, then the output will be "pretty" (not jarring) and "informative" (guiding the eye to the most relevant info).
I do really like diagramming tools that have a mode that kinda-sorta looks like a human sketch, though. I feel like it lets me not worry about the thing being pixel perfect.
The fewer right angles, the better: I can just draw shapes and put them in roughly the right spots and it'll look fine.
https://flowchart.fun/ recently helped me very quickly draw flow charts to understand process of a system. Best thing was how intuitive and fast I could iterate over. And it allows custom css for styling which helped a lot. IMO for flow charts, this is so far the easiest / quickest text based diagram tool.
Thanks for sharing. I love mermaid, and use it frequently. I’ll have to check out D2. I think declarative diagramming is a powerful tool to capture thoughts in a readable way that can be versioned like any other text.
Hi. This is really cool. I tried your example, and it rendered top to bottom instead of left to right (as in the directions).
The very first example: x -> y
I rendered the svg, and then loaded ONLY the svg into a browser window.
I then looked through the whole of the document and tried to find how to align the output... and couldn't find out how.
Since the linked instructional was diverging from real life results, I stopped using it. :(
If you know how to fix it or could update the directions to ensure reliable output to the directions... that would go a long way for visitors like myself :)
If only I could figure out how to handle branching in Mermaid like the ones after the "Saving" and "Sharing" labels in this animation: https://whimsical.com/
I was looking for some programatic way to create sequence diagrams and came across plantuml, but then I realised it sends your data to their servers so, while I can use for my personal projects, not using for company stuff.
Are there any other options to keep sequence diagrams as code and just render it on demand?
You can deploy a plantuml server internally (so that the rendering is done internally). Just running planuml.jar does not send anything to their servers either, it renders diagrams locally.
- it's rendered in the browser -> immediate feedback
- great autocomplete and syntax-check in the code editor
- great connection between graphic and text (click on element -> jump to relevant line)
- graphical drawing and reordering
- presentation view (fullscreen + keeps actors "sticky" on top)
Especially dragging/dropping actors around is a lot of fun when you try to find the most suitable presentation format for complex diagrams. I'm not aware of any other editor that has this good integration between the code-editor and the visual editor.
It's not open source, but it's been around for free for a long time.
You can create Plantuml diagrams without the server locally using this small Docker ( https://github.com/lrvl/text-to-bmp ) and use "make docker-plantuml"
I clicked the link hoping to see beautiful diagrams to impress my colleagues, but it didn't spark joy. I much prefer the aesthetic of graphviz/google drawings/LaTeX/ggplot2.
I think the author is too focused on details that aren't noticed, while the spacing/padding, colors, font, and font size they're using are ridiculous... Practically speaking, if you were to present this it would be illegible.
No this article has merely highlighted that when you do design things you have to improve it — like group things when it gets too cluttered. The designs and thoughts are simple discoveries one makes when making diagrams. As one can tell these designs are bare minimum blocks connected by lines and grouped visually because it gets crowded.
Part 2 is about adding colors and yet more things to this current design that are discoverable by using any existing drawing tool (draw.io, lucid, figma, even MS Paint).
In the alignment example from the post there’s a missed opportunity to align the components vertically based on their role
The caches should be next to each other, and the servers should be too, leaving the DB up top and the lib between the servers
Although personally I’d also then flip it to put the DB at the bottom so the server becomes the headline, and if one server is public and the other internal, then I’d push the internal one down half a row too
"Beautiful" is very hard to maintain when a system starts changing. Think of adding a new box to the middle of an already-busy diagram; it could take an hour to re-align everything. In the 2020s a dev's time is probably better spent using diagrams-as-code[0].
The author does touch on this subject that it's time consuming to amend a diagram. And it absolutely is, if only there was a standardized schema that could be followed properly and then have the tools have an "auto format" option..
For this reason I love drawing diagrams on whiteboards and absolutely hate taking the step of putting them into a wiki/README/etc.
One thing I miss about in-office work is that people would spontaneously draw diagrams in meetings. The same diagrams would get drawn over and over again, evolving. And everybody did it, so everybody was rehearsing the architecture in their heads and had a basic grasp of it. It was like a tribe singing the same songs over and over again, trying out variations and evolving the “official” version over time.
This doesn’t happen (IME) with remote work. Drawing diagrams takes for-fricken-ever so people tend not to do it in meetings. Best case, someone shows up with a diagram, and it stays up while people talk about different ways of doing it, and after the meeting someone makes the changes that were suggested.
It really lacks the collaborative value of someone walking up to the whiteboard and saying “what if we did this,” not hesitating to make changes because they can do it in ten seconds and then wipe out their changes and redraw the original in few seconds if they want.
When somebody starts making changes to a diagram in a remote meeting, it’s a sign you’re going to be there for a long, long time.
New macbooks can film the sheet of paper you’re writing onto, on the desk, turn it around, fix the perspective, and display it to others. That’s very clever, if true it’s a great replacement for a tablet.
One thing I miss about in-office work is that people would spontaneously draw diagrams in meetings. [...] This doesn’t happen (IME) with remote work. Drawing diagrams takes for-fricken-ever so people tend not to do it in meetings.
I agree. I’m a big fan of remote working in general but with current tools we’ve definitely lost something in this area. The practical utility of just having a huge whiteboard on the wall that everyone can see with a bunch of different coloured pens that anyone can pick up is enormous.
I hope the next generation of conferencing apps will provide shared “whiteboard” spaces as standard. Extra points if they can effectively use tablets (thinking Wacom not iPad here) so everyone can just sketch out ideas quickly and collaboratively again, and if it also provides useful and rapidly accessible tools for things like saving interesting work, editing and moving things around, and retrieving something you were looking at earlier in the discussion. I suspect there’s a significant opportunity here, a chance to fix one of the legitimate criticisms of WFH. Certainly among the smaller businesses I tend to work with, I could imagine any remote conferencing tool that got that right first would rapidly expand its market share.
The current generation mostly have shared whiteboards already I think (zoom, teams, etc).
Digital whiteboards aren't great, but they are useful. Interestingly though they dont' seem toe be used quite int he same way.
I still insist that for my teams all rooms that get used for meetings, formal or informal, have at least 1 big whiteboard. It's always paid off, and as you and GP note - nothing in WFH tooling quite works.
Hell, I've had team members WFH put a whiteboard in their house and an extra camera to show it; with mixed success. It's not collaborative, which reduces value. Tablets too. The workflows are all so-so.
The current generation mostly have shared witheboards already I think (zoom, teams, etc).
To the extent that this is true, I don’t think I’ve ever seen them used routinely in any team or organisation I’ve worked with. I believe a large part of this is because no-one has yet found a way to use a keyboard and mouse as quickly/casually/effectively as good old pen and paper (or, in this case, marker and whiteboard). Given that so much of our work now happens remotely, I’m a little surprised that stylus-friendly devices haven’t caught on more.
I don't know. I do know I've provided entire teams with stylus + letter-sizes pads (and smaller ones, and/or ipads) and tried all the available software (we could find, anyway) with pretty mixed results.
Would you mind elaborating on the “pretty mixed results”? I’ve been curious about trying this for a while, but it looks like you already have, so I’m very interested in what did or didn’t work well in your experience.
We never found a workflow that fully replaced taking turns drawing on a (shared) whiteboard.
Some people found the tools really pretty usable, so for them it was great for drawing a quick sketch and sharing with people, but it was always a bit clunky compared to physical pens. Oddly (perhaps?) some of the team were very self-conscious about drawing while others watched, more so than in person.
After a while we realized that some of the team was disengaging from the rest of conversation while sketching, in a way that noodling on paper didn't' seem to. Maybe because they were in a different physical space, so when eyes were focused on the drawing, there wasn't really much connection (other than audio)
Scaling is a problem in than nothing on a monitor seems to work as well on multiple scales as a big ass whiteboard. I mean, you can certainly represent more scales digitally, but you are pan-and-zooming all the time. The "single picture" part didn't seem to work as well.
Another thing is that we never found a digital place that has the same mental priority as big whiteboard in the common area. There was a lot of "where did we put that, is it attached to meeting or on the folder X or ...
On the whole I thought it was more positive than negative, but over time they were definitely being used less and less.
A couple of the team absolutely loved them for diagramming and completely replaced other tools for that.
To be fair, it was a "forced experiment" during covid lockdowns initially, so could certainly have been executed better.
A surface book 2 and Microsoft sketchpad do the job really well for a screen share.
However, there's skill involved, and you really want that multi touch+pen input.
Zoom in to write text, zoom out to draw boxes, move the canvas around, etc. Also, having a colour pallet, since that's designed into whiteboard markers for you, where digital systems give you a billion bad options
>One thing I miss about in-office work is that people would spontaneously draw diagrams in meetings. The same diagrams would get drawn over and over again, evolving. And everybody did it, so everybody was rehearsing the architecture in their heads and had a basic grasp of it. It was like a tribe singing the same songs over and over again, trying out variations and evolving the “official” version over time.
I got a laptop with a touch screen and baked in stylus. Screen share + paint is my white board. I can screenshot them and dump them into our chat logs. Works pretty well and people do seemingly find it charming.
We maintained a c4 model of our systems built for importing and displaying on structurizr.com and tbh, it wasn't fun. You don't get the same intuitive understanding and overview from the code that you get from a diagram and there was no fast local preview. You had to upload your code to the server.
Even worse was the fact that adding a new box usually meant realigning all arrows. As a consequence the diagrams were never kept up to date on a continuous basis.
I had a better experience using plantML for sequence diagrams. The task is easier so the output of the interpreter is typically useful without manual interventions.
FWIW You can do a C4 model using plantUML diagrams [1] imported directly into RST markdown (or inline, fwiw, but that makes live preview harder)
That way in an editor like VS Code (e.g. where you have/make plugins to support) you can live preview the diagram in your editor while editing the related text - both get syntax highlighting etc. Using a tool like sphinx to tie everything together helps, as you can easily (enough) write extensions to handle quirks of your own setup reasonable if needed.
I've seen this work pretty well, in a /doc folder in the git repo with some autogenerated reference links as well, from the same repo. You either need the plantUML jar file local (and java, obv) or to point it at a rendering instance "local enough".
Are we better off creating diagrams from code (turning text into graphics using layout engines), or code from diagrams (using WYSIWYG editors to interact with a declarative format)?
I think how worthwhile that time investment is depends on the reach and longevity of the diagram.
Sometimes you're only sketching something out to think things through and you'll get rid of it after 20 minutes.
But if at other times, if you've got reference material that's being used to onboard people or explain your system to other teams, etc. that hour spent creating something more understandable probably pays dividends & worth the effort.
And in moving things around and re-aliging you have to re-learn the whole diagram. If the frobnitz was always in the upper right part of the diagram and suddenly it's moved to the center left because everything lines up better that way, well maybe it's helpful to someone who is looking at the diagram for the first time but if you've been working with it for six months suddenly it looks like a completely different thing.
It's like an ugly UI. It may be ugly but the people who use it, know it. When you "clean it up" you've now disrupted their mental models and they have to re-learn it all over again.
I like D2 for this. In a previous role, I wrote a program to parse all of our serverless.yml files (we were doing micro services on AWE) and auto-generate a big D2 diagram from it. It was nice because it would auto-update as the system grew and I wrote it so that the diagram could be broken out into smaller diagrams for each sub system (think splitting on SNS topic)
It’s either PowerPoint or draw.io depending on the time I have and the complexity.
Then I found this web based coded solution 1 and I was having more fun then I deserved, especially to quickly add shapes, connections, and not worry too much how it is going to look aesthetically. But then I do worry how it is going to look and I can’t really force where I want the shapes and group them differently, and when I’m adapting myself to the tool instead of the other way around,… I go back to draw.io and screenshot to PowerPoint.
I don't understand the first example. The author talks about an unplanned node, literally called it "I was unplanned", and then says "if you have planned ahead"... How can I plan agead for something unplanned, in the context of a diagram? Do I leave sufficient white space around all nodes?
Also, the suggested improvement makes it look like "something" and "I was unplanned" are somehow related, or use the same channel/mechanism to interact with "engine"
Maybe there will be an LLM that specializes in reading code and generating diagrams.
It would be cool if it was able to turn those spaghetti class diagrams into something useful. I'd like to see such a tool make sense of the sprawling terraform we've got, diagrams of which always end up being huge and complex.
- Levels of abstraction
- A transaction
- An element inventory
- A process
- Inputs and outputs
Among others. Given the numbers of nodes and edges, the most beautiful or consistent layout would be implied using graph layouts. When we use boxes and lines, we imply meaning to their order and sizes, which might be the case, but most often there isn't, it's just where you had space on the page.
The best diagrams are ones you could describe using graphviz/dot because each relationship is a true statement about the system. Sequence diagrams are the next best ones because they force you to close the loop in your thinking, imo.
As an avid plantuml user, I don't think it's that simple. Graph layouts help, but it doesn't take long for automatic layouts to start to get in the way of conveying meaning, and that's even with a higher level description language, like plantuml or mermaid, let alone with raw graphviz. One can quickly start to spend more time trying to make the layout look right than actually evolving it.
Don't have a solution to it, unfortunately. When things in my head start to map too poorly to plantuml, I just consider drawio instead, but it's such a downgrade, that I try to avoid as much as I can.
I agree that layout auto-adjustments in flowcharts can be problematic, especially when subgraphs represent architectural subsystems as they are not really flowcharts. :)
I'm developing a new Mermaid diagram type for more layout control, with precise block placement.
> A visual model should distinguish between: - Levels of abstraction (...)
So much this! Most people entering the architecture trade mix infrastructure, application components, functional elements and business capabilities into the same diagram. That's ok as long as the diagram conveys the story but it complicates real fast.
There's strong parallels here with electrical schematics, circuit diagrams and other engineering drawings. There is no singular 'right' way to do it.
Just as with code, choosing good abstractions and methods of expression is what separates something from a grok-able idea to regrettable mess. It's not about beauty or aesthetics, it's a tool that requires some active thought and effort to design.
For me, keeping the abstraction level consistent is really hard sometimes. Especially with infrastructure diagrams, it's sometimes hard to stop the urge to add more details at different levels.
I wonder if there's a tool that would allow me to easily zoom into a diagram, kinda like those infinite zoomquilt animations.
I've been thinking and doing this for many years - I've tried very hard to do it with one diagram without luck
if you want them to look nice (and I do try to make them as artistic as possible) then I've found that the best/ only proper way to do it, is to do multiple diagrams for different groups of people.
complex/ messy one for infrastructure - showing interfaces/ IP address/ security zones/ resiliance/ physical locations/ application binaries/ OS info etc..
sequence diagrams for logic flow of applications
basic fancy ones for stake holders/ less technical ppl - crayon type of diagrams
for all the diagrams:
I find using matching colours (but try if possible, to consider color blind people) and levels of grey (try not to use black) work best...
try to group interfaces close together...
try not to have crossing lines...
symetrical as possible...
lines and boxes all aligned with something
Maybe this tool already exists, but it occurs to me that architecture diagrams could be generated from, say, Terraform HCL files. They mightn't be perfect, but if it gets you 80% of the way there -- for final touch-ups with some vector editor or, perhaps, using in-band pragmata via comments -- that seems like a no-brainer.
I'm a fan of whimsical.com - it's not code-driven, but does a pretty good job at aligning nodes when making, say a flowchart. Plus, they have a decent library of icons to use.
I attribute a large part of my technical leadership success to being able to communicate clearly through diagrams, and I think the post gives some good entry-level practical advice.
One more piece of advice I'd have is to either make sure your picture tells a story, or to be able to tell a story using your picture. Humans are social creatures who have learned to share information through stories, and you'll make a much bigger impression on others if you can weave your picture into your story.
The general competency level of diagramming in most engineering teams is low enough that I think it's better to talk about what to diagram rather than how to visually lay it out. Everyone has heard of sequence diagrams (and for good reason!) but do you use data flow diagrams?
Yes, though I don’t use the symbols suggested on that page as they don’t connect with people’s mental models very well.
I just overlay the flows of data on other diagrams, adding notes about the type of the data, and sometimes add info about particular fields, where useful.
Where I work it’s also useful to add the internal classification of the data, which allows understanding of the sensitivity level of the data and its retention policy.
I studied Structured Analysis at university and still have a couple of books on the subject, but I never used it professionally.
I had a lot more experience with UML, but that too has gone out of fashion.
Nobody models anything anymore, not even ER diagrams are used.
Knowledge ends up scattered between a million tasks in some project management software. Often, things are not even written down, because "there's not enough time".
One of the things I recommend to the startups I advise is to include documentation within the repository. I always try to have a /doc directory which includes Markdown (I like using [1] self rendering markdown pages) and MermaidJS (For which I also created a dumb self rendering script [2]).
That way Merge Requests can be blocked for lack of documentation, or lack of documentation update.
This is interesting, do you have an example repository with that setup? My team currently uses Swagger for documentation which provides decent documentation for us, so what sort of documentation at the repository level could I gain by using this setup instead or in combination? Also, how would one detect that the documentation has been correctly updated aside from manual inference?
One of the things I recommend to the startups I advise is to include documentation within the repository.
Agreed, this can help. I sometimes wonder, having written a substantial project in literate programming¹ style once, whether that approach doesn’t deserve more exploration. Then not only is your documentation kept in the same repo as your code, your source files themselves almost become documentation first and code second.
You definitely have to do a lot of things quite differently to how we typically do them today to make that idea work well, but I suspect it could be like a good static type system, incurring a modest extra cost up-front but with a big long-term pay-off once you’ve figured out the tools and processes to take advantage of it.
Oh man, if only it were just the diagrams that were missing. It's shocking how a lot of orgs have to get crazy large before they land on any kind of reasonably formal design-process.
Often, things are not even written down, because "there's not enough time".
This one is the epitome of the “If you think X is expensive, try [not doing X]” meme.
I’d take a decent software architecture diagram, a detailed data model with an ER diagram, and some form of useful written requirements over probably any other process or tool ever invented in the world of software. Alas, advocating such things in the era of Agile often feels like the curse of Cassandra.
155 comments
[ 3.1 ms ] story [ 222 ms ] threadIt requires making sone compromises, however: Box inside box does not always end well. It is a worthy tradeoff for me, as I can document things much faster, and you get a feel about what will or wont work after a few tries.
https://www.yworks.com/products/yed
Extract relations as tgf (trivial graph format), import, hierarchical layout.
tgf:
I also hear Scapple is good. Everything else is overengineered ime.
http://hackles.org/cgi-bin/archives.pl?request=9
http://hackles.org/cgi-bin/archives.pl?request=10
http://hackles.org/cgi-bin/archives.pl?request=11
I've always been slightly concerned it was possibly not the best use of time, but I have never had anyone tell me not to do it.
What I like about the article is that it articulates, in a practical way, how to make something more beautiful, whereas I go by feel.
Thanks for sharing.
Visualization goals!
I have somewhat avoided this because it can make you look like you're changing things for no good reason (no easily communicable reason, anyway).
I still do it when people have too much going on for a single line though (ternary ops + function calls + string/number formatting, etc which is very common in enterprise-y programs).
I get that ugly software diagrams are not fun to look at, but to me dressing them up is like adding curves to a line chart - yes it's visually appealing but it interferes with the data being conveyed.
Most diagrams have not had that must thought put into them. They should look a little ugly because that implies it might not be right so look for errors.
Weirdly, prettiness is the bigger red flag for me wrt to error. I see that and feel like more attention was put into that than the underlying information.
Ugly, brutalistic, utilitarian stuff tends to imply a focus on correctness to me.
If that means creating an overview of the system architecture for new team members that uses pretty colours and multiple fonts and icons and shaded boxes but that helps them to understand the system more quickly and correctly than an overwhelming page of black-and-white text and arrows, the extra styling has done its job.
Had to take Color Theory to get my BFA. We learned things like the "speed" of colors: yellow is the "fastest" and purple is the "slowest". Only a little yellow is needed to balance out a lot of purple. Same for balancing the other colors. You use these balances for guiding the eye (lots of yellow on a purple field).
When you keep this in mind, diagrams or not, then the output will be "pretty" (not jarring) and "informative" (guiding the eye to the most relevant info).
The fewer right angles, the better: I can just draw shapes and put them in roughly the right spots and it'll look fine.
The very first example: x -> y
I rendered the svg, and then loaded ONLY the svg into a browser window.
I then looked through the whole of the document and tried to find how to align the output... and couldn't find out how.
Since the linked instructional was diverging from real life results, I stopped using it. :(
If you know how to fix it or could update the directions to ensure reliable output to the directions... that would go a long way for visitors like myself :)
Edit: did a google search for "d2lang connection left to right" and ended up here: https://d2lang.com/tour/layouts/
which may be helpful to you for the question I surfaced as it isn't linked in your overview docs :)
In Gitlab they are rendered nicely when visiting the .md file with the web browser. Github doesn't have that functionality yet.
Are there any other options to keep sequence diagrams as code and just render it on demand?
Edit: http://blockdiag.com/en/seqdiag/examples.html seems to do what I'm looking for.
https://hub.docker.com/r/plantuml/plantuml-server
One thing I always seem to hit is the default diagram size/memory limits, the FAQ on plantuml.com has command-line switches to override those.
- syntax is really close to PlantUML
- it's rendered in the browser -> immediate feedback
- great autocomplete and syntax-check in the code editor
- great connection between graphic and text (click on element -> jump to relevant line)
- graphical drawing and reordering
- presentation view (fullscreen + keeps actors "sticky" on top)
Especially dragging/dropping actors around is a lot of fun when you try to find the most suitable presentation format for complex diagrams. I'm not aware of any other editor that has this good integration between the code-editor and the visual editor.
It's not open source, but it's been around for free for a long time.
I think the author is too focused on details that aren't noticed, while the spacing/padding, colors, font, and font size they're using are ridiculous... Practically speaking, if you were to present this it would be illegible.
Part 2 is about adding colors and yet more things to this current design that are discoverable by using any existing drawing tool (draw.io, lucid, figma, even MS Paint).
The caches should be next to each other, and the servers should be too, leaving the DB up top and the lib between the servers
Although personally I’d also then flip it to put the DB at the bottom so the server becomes the headline, and if one server is public and the other internal, then I’d push the internal one down half a row too
[0] https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
I personally find it far quicker to use the visual aid than learning a new syntax etc.
I don't think it's a joke, though.
One thing I miss about in-office work is that people would spontaneously draw diagrams in meetings. The same diagrams would get drawn over and over again, evolving. And everybody did it, so everybody was rehearsing the architecture in their heads and had a basic grasp of it. It was like a tribe singing the same songs over and over again, trying out variations and evolving the “official” version over time.
This doesn’t happen (IME) with remote work. Drawing diagrams takes for-fricken-ever so people tend not to do it in meetings. Best case, someone shows up with a diagram, and it stays up while people talk about different ways of doing it, and after the meeting someone makes the changes that were suggested.
It really lacks the collaborative value of someone walking up to the whiteboard and saying “what if we did this,” not hesitating to make changes because they can do it in ten seconds and then wipe out their changes and redraw the original in few seconds if they want.
When somebody starts making changes to a diagram in a remote meeting, it’s a sign you’re going to be there for a long, long time.
Take a picture of a hand drawn diagram and just paste the image.
Sure it's not vectored but wiki is, well, quick wiki-wiki.
That's a reference I haven't seen in over a decade. Nice!
I agree. I’m a big fan of remote working in general but with current tools we’ve definitely lost something in this area. The practical utility of just having a huge whiteboard on the wall that everyone can see with a bunch of different coloured pens that anyone can pick up is enormous.
I hope the next generation of conferencing apps will provide shared “whiteboard” spaces as standard. Extra points if they can effectively use tablets (thinking Wacom not iPad here) so everyone can just sketch out ideas quickly and collaboratively again, and if it also provides useful and rapidly accessible tools for things like saving interesting work, editing and moving things around, and retrieving something you were looking at earlier in the discussion. I suspect there’s a significant opportunity here, a chance to fix one of the legitimate criticisms of WFH. Certainly among the smaller businesses I tend to work with, I could imagine any remote conferencing tool that got that right first would rapidly expand its market share.
Digital whiteboards aren't great, but they are useful. Interestingly though they dont' seem toe be used quite int he same way.
I still insist that for my teams all rooms that get used for meetings, formal or informal, have at least 1 big whiteboard. It's always paid off, and as you and GP note - nothing in WFH tooling quite works.
Hell, I've had team members WFH put a whiteboard in their house and an extra camera to show it; with mixed success. It's not collaborative, which reduces value. Tablets too. The workflows are all so-so.
To the extent that this is true, I don’t think I’ve ever seen them used routinely in any team or organisation I’ve worked with. I believe a large part of this is because no-one has yet found a way to use a keyboard and mouse as quickly/casually/effectively as good old pen and paper (or, in this case, marker and whiteboard). Given that so much of our work now happens remotely, I’m a little surprised that stylus-friendly devices haven’t caught on more.
I have seen teams using these whiteboard tools to good effect, but they aren't used the way a whiteboard would be, typically.
Stylus friendly devices don't solve the whole thing either.
Maybe not today, but if everyone had stylus+pad and knew how to use the related software/UI, what else do you think would be useful?
We never found a workflow that fully replaced taking turns drawing on a (shared) whiteboard.
Some people found the tools really pretty usable, so for them it was great for drawing a quick sketch and sharing with people, but it was always a bit clunky compared to physical pens. Oddly (perhaps?) some of the team were very self-conscious about drawing while others watched, more so than in person.
After a while we realized that some of the team was disengaging from the rest of conversation while sketching, in a way that noodling on paper didn't' seem to. Maybe because they were in a different physical space, so when eyes were focused on the drawing, there wasn't really much connection (other than audio)
Scaling is a problem in than nothing on a monitor seems to work as well on multiple scales as a big ass whiteboard. I mean, you can certainly represent more scales digitally, but you are pan-and-zooming all the time. The "single picture" part didn't seem to work as well.
Another thing is that we never found a digital place that has the same mental priority as big whiteboard in the common area. There was a lot of "where did we put that, is it attached to meeting or on the folder X or ...
On the whole I thought it was more positive than negative, but over time they were definitely being used less and less.
A couple of the team absolutely loved them for diagramming and completely replaced other tools for that.
To be fair, it was a "forced experiment" during covid lockdowns initially, so could certainly have been executed better.
However, there's skill involved, and you really want that multi touch+pen input.
Zoom in to write text, zoom out to draw boxes, move the canvas around, etc. Also, having a colour pallet, since that's designed into whiteboard markers for you, where digital systems give you a billion bad options
I got a laptop with a touch screen and baked in stylus. Screen share + paint is my white board. I can screenshot them and dump them into our chat logs. Works pretty well and people do seemingly find it charming.
'One thing I miss about in-office work is that people would spontaneously draw diagrams in meetings.
The same diagrams would get drawn over and over again, evolving. And everybody did it'
I miss in online meetings the start with and highlevel outline diagram, and fill in different detailed sets depending on the conversation.
I like plantuml, but it's hard to do that as fast as a white board.
Also I found that repitionion of explaining your system to multiple sets outsiders really helper refine the content.
I had a better experience using plantML for sequence diagrams. The task is easier so the output of the interpreter is typically useful without manual interventions.
I found their Lite container version perfect for local iteration on diagrams: https://docs.structurizr.com/lite/quickstart
That way in an editor like VS Code (e.g. where you have/make plugins to support) you can live preview the diagram in your editor while editing the related text - both get syntax highlighting etc. Using a tool like sphinx to tie everything together helps, as you can easily (enough) write extensions to handle quirks of your own setup reasonable if needed.
I've seen this work pretty well, in a /doc folder in the git repo with some autogenerated reference links as well, from the same repo. You either need the plantUML jar file local (and java, obv) or to point it at a rendering instance "local enough".
[1] https://github.com/plantuml-stdlib/C4-PlantUML
Sometimes you're only sketching something out to think things through and you'll get rid of it after 20 minutes.
But if at other times, if you've got reference material that's being used to onboard people or explain your system to other teams, etc. that hour spent creating something more understandable probably pays dividends & worth the effort.
It's like an ugly UI. It may be ugly but the people who use it, know it. When you "clean it up" you've now disrupted their mental models and they have to re-learn it all over again.
If you want people to look at a diagram and see stuff in it, rather than brush it off by familiarity, you want to move some boxes around.
Then I found this web based coded solution 1 and I was having more fun then I deserved, especially to quickly add shapes, connections, and not worry too much how it is going to look aesthetically. But then I do worry how it is going to look and I can’t really force where I want the shapes and group them differently, and when I’m adapting myself to the tool instead of the other way around,… I go back to draw.io and screenshot to PowerPoint.
1 — https://nomnoml.com/
Will definitely try out nomnomi tho ..
Also, the suggested improvement makes it look like "something" and "I was unplanned" are somehow related, or use the same channel/mechanism to interact with "engine"
It would be cool if it was able to turn those spaghetti class diagrams into something useful. I'd like to see such a tool make sense of the sprawling terraform we've got, diagrams of which always end up being huge and complex.
- Levels of abstraction - A transaction - An element inventory - A process - Inputs and outputs
Among others. Given the numbers of nodes and edges, the most beautiful or consistent layout would be implied using graph layouts. When we use boxes and lines, we imply meaning to their order and sizes, which might be the case, but most often there isn't, it's just where you had space on the page.
The best diagrams are ones you could describe using graphviz/dot because each relationship is a true statement about the system. Sequence diagrams are the next best ones because they force you to close the loop in your thinking, imo.
Don't have a solution to it, unfortunately. When things in my head start to map too poorly to plantuml, I just consider drawio instead, but it's such a downgrade, that I try to avoid as much as I can.
I agree that layout auto-adjustments in flowcharts can be problematic, especially when subgraphs represent architectural subsystems as they are not really flowcharts. :)
I'm developing a new Mermaid diagram type for more layout control, with precise block placement.
So much this! Most people entering the architecture trade mix infrastructure, application components, functional elements and business capabilities into the same diagram. That's ok as long as the diagram conveys the story but it complicates real fast.
Just as with code, choosing good abstractions and methods of expression is what separates something from a grok-able idea to regrettable mess. It's not about beauty or aesthetics, it's a tool that requires some active thought and effort to design.
I wonder if there's a tool that would allow me to easily zoom into a diagram, kinda like those infinite zoomquilt animations.
Ilograph and Structurizr are zoomable. (Full disclosure: I am developing the former)
Uses the C4 diagramming model and looks really slick exactly for capturing this type of detail
if you want them to look nice (and I do try to make them as artistic as possible) then I've found that the best/ only proper way to do it, is to do multiple diagrams for different groups of people.
complex/ messy one for infrastructure - showing interfaces/ IP address/ security zones/ resiliance/ physical locations/ application binaries/ OS info etc..
sequence diagrams for logic flow of applications
basic fancy ones for stake holders/ less technical ppl - crayon type of diagrams
for all the diagrams: I find using matching colours (but try if possible, to consider color blind people) and levels of grey (try not to use black) work best... try to group interfaces close together... try not to have crossing lines... symetrical as possible... lines and boxes all aligned with something
https://developer.hashicorp.com/terraform/cli/commands/graph
Is there a tool out there that lets me define them in code somehow? For example, neighbor distance or what symmetry means in a given context?
One more piece of advice I'd have is to either make sure your picture tells a story, or to be able to tell a story using your picture. Humans are social creatures who have learned to share information through stories, and you'll make a much bigger impression on others if you can weave your picture into your story.
The story is especially handy when you're drawing it in real time on a whiteboard
https://en.m.wikipedia.org/wiki/Data-flow_diagram
I just overlay the flows of data on other diagrams, adding notes about the type of the data, and sometimes add info about particular fields, where useful.
Where I work it’s also useful to add the internal classification of the data, which allows understanding of the sensitivity level of the data and its retention policy.
I had a lot more experience with UML, but that too has gone out of fashion.
Nobody models anything anymore, not even ER diagrams are used.
Knowledge ends up scattered between a million tasks in some project management software. Often, things are not even written down, because "there's not enough time".
That way Merge Requests can be blocked for lack of documentation, or lack of documentation update.
MermaidJS have been a godsend for documentation.
[1] https://github.com/jcbhmr/ezmdpage
[2] https://github.com/obaqueiro/mermaid-js-auto-renderer
Agreed, this can help. I sometimes wonder, having written a substantial project in literate programming¹ style once, whether that approach doesn’t deserve more exploration. Then not only is your documentation kept in the same repo as your code, your source files themselves almost become documentation first and code second.
You definitely have to do a lot of things quite differently to how we typically do them today to make that idea work well, but I suspect it could be like a good static type system, incurring a modest extra cost up-front but with a big long-term pay-off once you’ve figured out the tools and processes to take advantage of it.
¹ https://en.wikipedia.org/wiki/Literate_programming
This one is the epitome of the “If you think X is expensive, try [not doing X]” meme.
I’d take a decent software architecture diagram, a detailed data model with an ER diagram, and some form of useful written requirements over probably any other process or tool ever invented in the world of software. Alas, advocating such things in the era of Agile often feels like the curse of Cassandra.