News for hackers. Stuff that matters.
Re:How to draw beautiful software architecture diagrams (2022) by Veuxdo on Friday October 27, 2023 @07:44AM (#38037258)
"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...

Re:How to draw beautiful software architecture diagrams (2022) by renegade-otter on Friday October 27, 2023 @08:31AM (#38037578)
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.

Re:How to draw beautiful software architecture diagrams (2022) by gtirloni on Friday October 27, 2023 @08:39AM (#38037663)
Definitely the sad reality. Things never align in intuitive ways, connect at the wrong sides, take circles around when there are shorter paths, etc.
Re:How to draw beautiful software architecture diagrams (2022) by dkarl on Friday October 27, 2023 @10:37AM (#38039038)
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.

Re:How to draw beautiful software architecture diagrams (2022) by zoomablemind on Friday October 27, 2023 @11:17AM (#38039609)
> ...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.

Re:How to draw beautiful software architecture diagrams (2022) by TeMPOraL on Friday October 27, 2023 @01:31PM (#38041395)
> wiki-wiki

That's a reference I haven't seen in over a decade. Nice!

Re:How to draw beautiful software architecture diagrams (2022) by eastbound on Friday October 27, 2023 @02:46PM (#38042341)
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.
Re:How to draw beautiful software architecture diagrams (2022) by ewi_ on Friday October 27, 2023 @11:41AM (#38039990)
Excalidraw has been great for me and my team to create diagrams on the fly during meetings.
Re:How to draw beautiful software architecture diagrams (2022) by b0tch7 on Friday October 27, 2023 @04:38PM (#38043599)
Came here to say the same. It's the only tool I'm comfortable creating visuals live / on-the-fly with
Re:How to draw beautiful software architecture diagrams (2022) by Chris_Newton on Friday October 27, 2023 @12:36PM (#38040680)
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.

Re:How to draw beautiful software architecture diagrams (2022) by ska on Friday October 27, 2023 @01:52PM (#38041652)
The current generation mostly have shared witheboards 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.

Re:How to draw beautiful software architecture diagrams (2022) by Chris_Newton on Friday October 27, 2023 @02:52PM (#38042400)
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.

Re:How to draw beautiful software architecture diagrams (2022) by ska on Friday October 27, 2023 @02:58PM (#38042469)
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.

Re:How to draw beautiful software architecture diagrams (2022) by Chris_Newton on Friday October 27, 2023 @03:20PM (#38042709)
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?

Re:How to draw beautiful software architecture diagrams (2022) by ska on Friday October 27, 2023 @03:28PM (#38042795)
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.
Re:How to draw beautiful software architecture diagrams (2022) by Chris_Newton on Friday October 27, 2023 @04:19PM (#38043396)
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.
Re:How to draw beautiful software architecture diagrams (2022) by ska on Friday October 27, 2023 @04:46PM (#38043709)
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.

Re:How to draw beautiful software architecture diagrams (2022) by Chris_Newton on Friday October 27, 2023 @04:54PM (#38043789)
That was interesting and not always what I’d have expected. Thanks! :-)
Re:How to draw beautiful software architecture diagrams (2022) by 8note on Friday October 27, 2023 @04:30PM (#38043505)
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

Re:How to draw beautiful software architecture diagrams (2022) by rjbwork on Friday October 27, 2023 @05:35PM (#38044306)
>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.

Re:How to draw beautiful software architecture diagrams (2022) by rightonbrother on Saturday October 28, 2023 @07:25PM (#38054443)
I agree with your comment so much I created a login.

'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.

Re:How to draw beautiful software architecture diagrams (2022) by tamiral on Friday October 27, 2023 @12:00PM (#38040238)
its the painful reality ... gotta love visio for that i thought upgrading the the latest Visio would help easy my alignment issues but nope!
Re:How to draw beautiful software architecture diagrams (2022) by bilekas on Friday October 27, 2023 @08:15AM (#38037480)
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..
Re:How to draw beautiful software architecture diagrams (2022) by gpderetta on Friday October 27, 2023 @08:15AM (#38037476)
I refuse to use WYSIWYG interfaces to draw diagrams (looking at you confluence!). Mermaid.js (or really any graphing language) it is for me.
Re:How to draw beautiful software architecture diagrams (2022) by bilekas on Friday October 27, 2023 @08:17AM (#38037487)
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.

Re:How to draw beautiful software architecture diagrams (2022) by puchatek on Friday October 27, 2023 @08:46AM (#38037717)
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.

Re:How to draw beautiful software architecture diagrams (2022) by jk563 on Friday October 27, 2023 @08:53AM (#38037775)
> no fast local preview

I found their Lite container version perfect for local iteration on diagrams: https://docs.structurizr.com/lite/quickstart

Re:How to draw beautiful software architecture diagrams (2022) by ska on Friday October 27, 2023 @01:15PM (#38041171)
FWIW You can do a C4 model using plantUML diagrams [1] imported directly into RST markdown.

That way in an editor like VSCode (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

Re:How to draw beautiful software architecture diagrams (2022) by nyanpasu64 on Friday October 27, 2023 @08:50AM (#38037744)
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)?
Re:How to draw beautiful software architecture diagrams (2022) by another-dave on Friday October 27, 2023 @10:25AM (#38038863)
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.

Re:How to draw beautiful software architecture diagrams (2022) by SoftTalker on Friday October 27, 2023 @01:47PM (#38041602)
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.

Re:How to draw beautiful software architecture diagrams (2022) by 8note on Friday October 27, 2023 @04:32PM (#38043540)
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.