6 ms·

"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

by Veuxdo 3y ago

"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-and-drop-diagram-tools/ https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

another-dave 3y ago
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 3y ago
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 3y ago
  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.
bilekas 3y ago
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..
gpderetta 3y ago
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 3y ago
  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.
renegade-otter 3y ago
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.
- dkarl 3y ago
  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 3y ago
    > ...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 3y ago
      > wiki-wiki That's a reference I haven't seen in over a decade. Nice!
    - eastbound 3y ago
      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.
puchatek 3y ago
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.
- ska 3y ago
  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 https://github.com/plantuml-stdlib/C4-PlantUML
- jk563 3y ago
  > no fast local preview I found their Lite container version perfect for local iteration on diagrams: https://docs.structurizr.com/lite/quickstart https://docs.structurizr.com/lite/quickstart
nyanpasu64 3y ago
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)?

by Veuxdo 3y ago

another-dave 3y ago

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 3y ago

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 3y ago
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.

bilekas 3y ago

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

gpderetta 3y ago

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 3y ago
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.

renegade-otter 3y ago

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.

dkarl 3y ago
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 3y ago
  > ...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 3y ago
    > wiki-wiki That's a reference I haven't seen in over a decade. Nice!
  - eastbound 3y ago
    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.

puchatek 3y ago

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.

ska 3y ago
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 https://github.com/plantuml-stdlib/C4-PlantUML
jk563 3y ago
> no fast local preview I found their Lite container version perfect for local iteration on diagrams: https://docs.structurizr.com/lite/quickstart https://docs.structurizr.com/lite/quickstart

nyanpasu64 3y ago

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)?