[HN Gopher] How to draw software architecture diagrams (2022)
___________________________________________________________________
How to draw software architecture diagrams (2022)
Author : walterbell
Score : 289 points
Date : 2023-10-27 06:57 UTC (16 hours ago)
(HTM) web link (terrastruct.com)
(TXT) w3m dump (terrastruct.com)
| hyperman1 wrote:
| 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.
| lstamour wrote:
| I use OmniGraffle for similar reasons :)
| walterbell wrote:
| 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.
| hyperman1 wrote:
| 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.
|
| https://www.yworks.com/products/yed
| w10-1 wrote:
| ditto. There's no reason to draw anything.
|
| Extract relations as tgf (trivial graph format), import,
| hierarchical layout.
|
| tgf: from, to, relation ...
| forward-slashed wrote:
| Whimsical is the obvious choice for me to draw diagrams. Well-
| designed, beautiful, and ergonomic.
|
| I also hear Scapple is good. Everything else is overengineered
| ime.
| viraptor wrote:
| 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)
| smokel wrote:
| 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.
| bluGill wrote:
| 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.
| tanepiper wrote:
| 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.
| sampo wrote:
| Here is how to do it with Gimp:
|
| 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
| walterbell wrote:
| Reminiscent of Bret Victor's visualization of live coding, this
| D2 OSS demo incrementally visualizes a database from SQL
| statements, generating SVG+text:
| https://terrastruct.com/blog/post/generate-diagrams-programm...
| Veuxdo wrote:
| Well it is the same company blog
| walterbell wrote:
| 2012 Bret Victor video ("Inventing on Principle",
| https://www.youtube.com/watch?v=PUv66718DII) preceded D2 by
| ten years.
| genericlogic wrote:
| 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.
|
| Thanks for sharing.
| walterbell wrote:
| _> 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._
|
| Visualization goals!
| hhjinks wrote:
| 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.
| vsareto wrote:
| >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).
| Bluecobra wrote:
| 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.
| dtjb wrote:
| 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.
| esafak wrote:
| That's what markup is for; it saves you from unproductive
| embellishment. Obviously, this does not apply for coding.
| victorbjorklund wrote:
| I been enjoying D2 lang for creating diagrams. It is like
| mermaid.js but more formatting options and, imo, better syntax. I
| wrote a small blog post about it:
| https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...
| nkozyra wrote:
| 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.
| bluGill wrote:
| 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.
| nkozyra wrote:
| > 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.
| Chris_Newton wrote:
| 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.
| bluGill wrote:
| 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.
| Chris_Newton wrote:
| 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.
| bluGill wrote:
| 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.
| ska wrote:
| This is true, and why some diagramming packages include
| "draft" modes that intentionally change the presentation
| to make it look less permanent/polished looking.
| ompogUe wrote:
| Well, colors can be both pretty and informative.
|
| 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).
| rrrrrrrrrrrryan wrote:
| 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.
| tincholio wrote:
| D2 has a very good layout engine (tala), but its use requires a
| paid license. The other two engines aren't nearly as good.
| smusamashah wrote:
| 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.
| Anduia wrote:
| In case you didn't already, if your project is documented with
| markdown, add ```plantuml blocks to insert your diagrams instead
| of separate binaries.
|
| In Gitlab they are rendered nicely when visiting the .md file
| with the web browser. Github doesn't have that functionality yet.
| jalk wrote:
| GitHub uses mermaid https://docs.github.com/en/get-
| started/writing-on-github/wor...
| livrem wrote:
| Fossil has built-in pikchr-rendering in Markdown (and on Wiki
| pages) that use the same method (but ```pikchr instead,
| unsurprisingly):
| https://pikchr.org/home/doc/trunk/doc/usepikchr.md
| vishnudeva wrote:
| Mermaid and C4 Model gang assemble!
| esafak wrote:
| 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/
| hashtag-til wrote:
| 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?
|
| Edit: http://blockdiag.com/en/seqdiag/examples.html seems to do
| what I'm looking for.
| fhd2 wrote:
| You can just download the plantuml.jar and run it with `java
| -jar planting.jar`, that's how I usually work with it.
| hashtag-til wrote:
| That sounds like a good idea. Just seen they have a Docker
| image as well.
|
| https://hub.docker.com/r/plantuml/plantuml-server
| sanitycheck wrote:
| Plus a bunch of plugins for VS Code and major IDEs.
|
| 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.
| ink_13 wrote:
| Indeed there is: https://www.websequencediagrams.com/
| Fethbita wrote:
| 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.
| maho wrote:
| I really like https://sequencediagram.org/
|
| - 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.
| Datagenerator wrote:
| 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"
| munro wrote:
| 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.
| 8organicbits wrote:
| The answer may be in the last paragraph, this is the first of a
| series.
| dpflan wrote:
| 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).
| walterbell wrote:
| Sample code and generated images for several tools:
| https://text-to-diagram.com
| bloopernova wrote:
| That's really useful, thank you for sharing it. D2 looks to
| be pretty good compared to the others.
| Veuxdo wrote:
| Be advised that the company behind the linked site
| (Terrastruct) are also behind D2.
| glenjamin wrote:
| 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
| Veuxdo wrote:
| "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].
|
| [0] https://www.ilograph.com/blog/posts/its-time-to-drop-drag-
| an...
| gpderetta wrote:
| I refuse to use WYSIWYG interfaces to draw diagrams (looking at
| you confluence!). Mermaid.js (or really any graphing language)
| it is for me.
| bilekas wrote:
| Wysiwyg is actually fine, but the underlying graphing
| language just doesn't seem to be standardized across multiple
| tools.
|
| I personally find it far quicker to use the visual aid than
| learning a new syntax etc.
| bilekas wrote:
| 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..
| renegade-otter wrote:
| I always joke that 10% of creating diagrams is actually
| creating diagrams and 90% is aligning arrows.
|
| I don't think it's a joke, though.
| gtirloni wrote:
| Definitely the sad reality. Things never align in intuitive
| ways, connect at the wrong sides, take circles around when
| there are shorter paths, etc.
| dkarl wrote:
| 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.
| zoomablemind wrote:
| > ...absolutely hate taking the step of putting them into a
| wiki/README/etc.
|
| 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.
| TeMPOraL wrote:
| > _wiki-wiki_
|
| That's a reference I haven't seen in over a decade. Nice!
| eastbound wrote:
| 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.
| ewi_ wrote:
| Excalidraw has been great for me and my team to create
| diagrams on the fly during meetings.
| b0tch7 wrote:
| Came here to say the same. It's the only tool I'm
| comfortable creating visuals live / on-the-fly with
| Chris_Newton wrote:
| _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.
| ska wrote:
| 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.
| Chris_Newton wrote:
| _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.
| ska wrote:
| Right. they exist, but they aren't great. I'm not sure if
| it is solveable without a significant shift.
|
| 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.
| Chris_Newton wrote:
| _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?
| ska wrote:
| 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.
| Chris_Newton wrote:
| 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.
| ska wrote:
| Sure!
|
| 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.
| Chris_Newton wrote:
| That was interesting and not always what I'd have
| expected. Thanks! :-)
| 8note wrote:
| 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
| rjbwork wrote:
| >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.
| tamiral wrote:
| its the painful reality ... gotta love visio for that i
| thought upgrading the the latest Visio would help easy my
| alignment issues but nope!
| puchatek wrote:
| 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.
| jk563 wrote:
| > no fast local preview
|
| I found their Lite container version perfect for local
| iteration on diagrams:
| https://docs.structurizr.com/lite/quickstart
| ska wrote:
| 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".
|
| [1] https://github.com/plantuml-stdlib/C4-PlantUML
| nyanpasu64 wrote:
| 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)?
| another-dave wrote:
| 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.
| SoftTalker wrote:
| 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.
| 8note wrote:
| That's a feature more than a bug.
|
| 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.
| poidos wrote:
| 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)
| lwhi wrote:
| I like draw.io ..
| lencastre wrote:
| 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.
|
| 1 -- https://nomnoml.com/
| lwhi wrote:
| That looks nice; but for flexibility, consistency and
| getting the job done draw.io is great IMO.
|
| Will definitely try out nomnomi tho ..
| beAbU wrote:
| 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"
| bloopernova wrote:
| 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.
| motohagiography wrote:
| A visual model should distinguish between:
|
| - 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.
| tonnydourado wrote:
| 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.
| knsv wrote:
| Knut, Mermaid's creator here.
|
| 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.
| tonnydourado wrote:
| Cool! I'm still on the plantuml train, but I like how much
| easier mermaid is to integrate with (no need for java), so
| I'm happy to see it evolve!
| pantulis wrote:
| > 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.
| hkon wrote:
| just give me a tool like enterprise architect with all the
| drawing capabilities and none of the enterprise features.
| _kb wrote:
| 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.
| gtirloni wrote:
| 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.
| Veuxdo wrote:
| > 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)
| ethanbond wrote:
| Also consider checking out icepanel.io
|
| Uses the C4 diagramming model and looks really slick exactly
| for capturing this type of detail
| 123pie123 wrote:
| 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
| justin_oaks wrote:
| I wish it were easier to make interactive diagrams where
| you can turn detail on and off or click on a section to
| zoom in and show more detail
| 123pie123 wrote:
| you try using layers - I know Visio has this, but
| everytime I've tried it was more trouble than just doing
| another diagram.
| Xophmeister wrote:
| 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.
| bloopernova wrote:
| terraform graph
|
| Is what currently exists, it generates graphviz that you can
| then edit to polish.
|
| https://developer.hashicorp.com/terraform/cli/commands/graph
| gtirloni wrote:
| These are awesome tips but hard to get right for people without
| graphical chops.
|
| 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?
| vich wrote:
| 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.
| jankar wrote:
| evergreen content on good visual design of software architect
| diagrams: http://www.fmc-modeling.org/visualization_guidelines
| walterbell wrote:
| thanks for the quality reference & offline PDF, http://www.fmc-
| modeling.org/download/visualization_guideline...
| jxf wrote:
| 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.
| 8note wrote:
| Same here, and I thought it was missing the first step of the
| drawing, which is defining what it is that you're trying to get
| across.
|
| The story is especially handy when you're drawing it in real
| time on a whiteboard
| tdba wrote:
| 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?
|
| https://en.m.wikipedia.org/wiki/Data-flow_diagram
| tokamak-teapot wrote:
| 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.
| tamiral wrote:
| most places i've worked at had no semblence of data flow
| diagrams!
| forinti wrote:
| 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".
| xtracto wrote:
| 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.
|
| MermaidJS have been a godsend for documentation.
|
| [1] https://github.com/jcbhmr/ezmdpage
|
| [2] https://github.com/obaqueiro/mermaid-js-auto-renderer
| Hel5inki wrote:
| 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?
| fijiaarone wrote:
| Swagger is not documentation, it is is a way to generate
| executable API examples from code comments.
| Chris_Newton wrote:
| _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 programming1 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.
|
| 1 https://en.wikipedia.org/wiki/Literate_programming
| photonthug wrote:
| 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.
| Chris_Newton wrote:
| _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.
| darkwater wrote:
| And that's why, kids, it takes me always a week to draw a simple
| diagram.
|
| That arrow is unaligned, I have to fix it.
|
| I forgot to add that component, now I have to shuffle things
| around.
|
| Let's group all these blocks together so I can move them. Wait, I
| need to add another block inside, I have to ungroup them and
| shuffle.
|
| etc etc etc
| gnuser wrote:
| I highly suggest those interested in this topic check out the
| blockdiag group of applications (blockdiag, nwdiag, seqdiag,
| rackdiag) Its been a year or so since I last did an eval of all
| the options and I keep returning to them. I prefer to have git
| post-recieve hooks that auto rebuild the images on commit. I
| liked mermaid but found some major limitations but the
| brilliantly named python "diagrams" is something I use sometimes
| as well. With all the font/image improvements you can use on both
| you can get some very nice stuff going.
| peteradio wrote:
| Diagrams should generate themselves. Is there a good markup that
| does this well? I hate manually manipulating boxes and arrows,
| can't be assed.
| bobobob420 wrote:
| I am really jealous of few people I know who intuitely draw
| amazing diagrams. Some of them are not even good engineers but
| can draw great looking diagrams. For me its a constant practice
| to get better and better but I still get amazed when I see high
| quality diagrams. Visual aesthetics are all around underrated,
| good diagrams are just so pleasing to look at.
| rperez333 wrote:
| What would be a good library /tool to auto arrange a complex
| graph (DAG) like the Blender/Unreal/Houdini node interfaces?
|
| I would expect some options to set constraints, like the first
| input staying always aligned with the previous node.
|
| Here is one of these DAGs:
| https://cdnb.artstation.com/p/assets/images/images/026/099/2...
| IshKebab wrote:
| Graphviz is the classic option but unfortunately it isn't very
| good. I mean it was great when it was written in the 80s or
| whatever but then it seems like it was declared "done" and is
| still stuck in the 80s.
|
| Quite annoying because it totally dominates the mindshare of
| graph layout tools, making it difficult to find alternatives.
|
| Here's some other options anyway:
|
| * Eclipse Layout Kernel: https://github.com/eclipse/elk
|
| * OGDF: https://ogdf.uos.de/
|
| In fairness both their websites are pretty terrible (would some
| examples kill you OGDF?) and they don't provide an easy way to
| try them out, so I guess it's not that surprising that Graphviz
| dominates.
|
| Anyway in practice if you have a complex graph then doing it
| manually is by far the best option.
|
| If it's too big to do manually then it's unlikely to be a
| useful graph in the first place.
| exabrial wrote:
| There was once a specification for diagrams called UML. It got
| laughed out of existence by the egos of developers unfortunately
| with the dawning of Agile.
|
| I believe Dilbert had a comic about it...
| nkozyra wrote:
| There's nothing really wrong about UML, but I find that its
| association with legacy software development kind of hurts it
| more than its actual spec and intent.
|
| I think the biggest thing a diagram should show you is the way
| data can and cannot flow. People tend to overcomplicate them
| with detail that's better suited for a corresponding text
| document. It's a visual, it should convey things quickly and
| without much noise.
| danielvaughn wrote:
| The aesthetics of those diagrams strongly remind me of whimsical:
| https://whimsical.com
| dingi wrote:
| Although I've never heard of D2 until now, it seems like too much
| programming for a diagramming language. I've used PlantUML for
| diagramming since couple years and it seems good enough. You need
| to learn their DSL but you don't have to manipulate visual
| entities manually.
| WillAdams wrote:
| Every time diagramming comes up in this context, I want to ask
| the question:
|
| >What does an algorithm look like?
|
| Why isn't it possible to represent a program visually?
|
| Why do complex efforts along these lines either evolve to:
|
| https://blueprintsfromhell.tumblr.com/
|
| or
|
| https://scriptsofanotherdimension.tumblr.com/
|
| or devolve to nothing more than labeled boxes and a wall of text
| not markedly more intelligible than the textual program source
| itself?
| emmanueloga_ wrote:
| My feeling is that the problem is trying to represent the
| _entire_ program space in a single diagram. I suspect the
| solution is to slice the representation by meaningful aspects.
|
| For instance, if you have boxes and arrows, maybe just focus in
| a single box, its inputs and its outputs. This is how it's done
| for electronics circuits, for instance: you don't need to
| understand everything about the internal components of, say, a
| 555 ic, just some model of how it works.
|
| I also think of blueprints, where projections of the 3d object
| are displayed together with the object.
| poorlyknit wrote:
| > Why isn't it possible to represent a program visually?
|
| I'd argue that the visual representation necessarily needs to
| abstract from the actual code to be useful. From concrete to
| abstract you can choose from any number of notations, e.g.
|
| - Control Flow Graph - Data Flow Graph - Jackson Notation -
| State Diagram
|
| etc. etc.
| pimlottc wrote:
| These are generally good tips for visual balance and legibility,
| but also keep in mind that the main purpose of a diagram is to
| promote understanding. Visual qualities like symmetry, alignment,
| relative shape and size imply relationships between nodes, like
| whether two systems have similar roles, capacity or importance.
|
| In one of their examples, there's an "unplanned" node that's
| placed awkwardly on far side; but maybe that's actually helpful
| to know! Maybe it's an ugly hack and should stay over there until
| it's better integrated into the core design.
|
| So just make sure the diagram is helpful and accurate first and
| foremost, then worry about tidying things up. And maybe leave
| some of the imperfect parts looking a bit more imperfect...
| artur_makly wrote:
| We're about to launch v1.0 of https://VisualFlows.io
|
| Within just few minutes, I was able to design this animated
| "architectural" map [0]of our parent SaaS.
|
| [0]
| https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
|
| Notable features include:
|
| - Smart Sections[1] - Smart Edges - Smart Node Deletion -
| Dark/Light modes - Embeddable - Drag n Drop images/svgs/gifs -
| AWS/Windows/Google Icons -- Markdown(*next week)
|
| [1]https://support.visualsitemaps.com/en/articles/6477269-how-t..
| .
| stuartjohnson12 wrote:
| Why should I use this over the more mature
| https://whimsical.com that has the same aesthetic?
| fijiaarone wrote:
| The article is correct in its esthetics but all it does is
| highlight the problem of how bad diagramming tools still are --
| and that they are so bad that a cell phone photo of a smudged
| whiteboard drawing with horrible handwriting is still preferable,
| but of course, also uneditable.
| _andrei_ wrote:
| For anyone who likes excalidraw & tldraw, there's this wrapper
| that handles local storage: https://github.com/revezone/revezone
| _andrei_ wrote:
| Curated list of solutions: - excalidraw -
| https://github.com/alswl/excalidraw-collaboration -
| revezone - excalidraw + tldraw -
| https://github.com/revezone/revezone - code2flow - code -
| https://app.code2flow.com - zenuml - code -
| https://app.zenuml.com - bpmn sketch miner -
| https://www.bpmn-sketch-
| miner.ai/examples/syntax-0-00-overview.html - d2lang -
| https://play.d2lang.com - mermaid - https://mermaid.live
| - diagram.codes - https://www.diagram.codes - kroki -
| https://kroki.io - nomnoml - https://www.nomnoml.com
| - azimutt - db, paid - https://azimutt.app - drakon -
| https://drakonhub.com/try-me - svgbob -
| https://ivanceras.github.io/svgbob-editor - typograms -
| https://code.sgo.to/typograms - argdown - for
| argumentation - https://argdown.org - flowchart.fun -
| paid - https://flowchart.fun - penrose - advanced,
| general - https://penrose.cs.cmu.edu - structurizr -
| https://structurizr.com/dsl - state machine cat -
| https://state-machine-cat.js.org - drawthe -
| http://go.drawthe.net - swimlanes.io -
| https://swimlanes.io - js-sequence-diagrams -
| https://bramp.github.io/js-sequence-diagrams -
| dbdiagram.io - https://dbdiagram.io/d -
| quickdbdiagrams.com - https://app.quickdatabasediagrams.com
| - edotor - https://edotor.net - pikchr -
| https://pikchr.org
|
| Did some research, I'm working on my own diagramming solution
| for software design.
| ciceryadam wrote:
| I quite like https://diagrams.mingrammer.com/
| glitchc wrote:
| It's always bugged me that large language models are possible,
| and yet no one can write a locally available tool that can reflow
| blocks and arrows to achieve aesthetic beauty. Omnigraffle comes
| close, but there's nothing available on Linux and Windows is
| still stuck with Visio.
|
| Now I know folks are going to suggest programmable interfaces
| like GraphViz and Plantuml, but those are not the same thing.
|
| Why can't there be a tool where I just draw the boxes and arrows,
| and the tool aligns everything to make it look pretty?
| rakkhi wrote:
| Awesome thank you. Added D2 lang to my blog post on this topic:
| https://open.substack.com/pub/rakkhi/p/cyber-security-design...
___________________________________________________________________
(page generated 2023-10-27 23:01 UTC)