4 ms·

The correct solution is a synthesis: generate the boxes and arrows from code. Then let a human hide, move, and style those objects. When the code changes, the b

The correct solution is a synthesis: generate the boxes and arrows from code. Then let a human hide, move, and style those objects. When the code changes, the boxes and arrows will change, and perhaps the style will want to change, but at least the diagram will remain correct. This is precisely the distinction between semantic markup and css, btw. Implying that the html would be auto generated, the css would be hand crafted.

falcor84 3y ago
I would actually be really interested in a bi-directional workflow, such that I would also be able to perform system redesign by changing the diagram's connections - the tooling will then automatically update the interface and the tests such that I wouldn't be able to commit my changes until the implementation matches the diagram.
- Sophistifunk 3y ago
  IMO the source code to aspects of the system that are best shown as graphs should be the graphs.
- jakewins 3y ago
  I realize this isn’t what you’re arguing for, but as a cautionary anecdote on this topic: Paul alludes to it in his post about Healthcare.gov from the other day, but this was apparently one of the major parts of the failure there - endless lines of code generated from UML diagrams, making reading the code hard and things like “can we add a trace statement here” difficult. Optimising for diagrams-as-source-of-truth has drawbacks for debugging and maintainability of the running code https://www.pauladamsmith.com/blog/2023/10/the-10-year-anniversary-of-the-healthcare.gov-rescue.html https://www.pauladamsmith.com/blog/2023/10/the-10-year-anniv...
bdg 3y ago
This requires a preset architecture standard that explains specifically what boxes and arrows are, and how boxes/arrows interact. Lots of software smears a logical box out over several folders in the code, sometimes even with entirely different names. I don't just mean people write non-cohesive code, I mean frameworks tend to prefer organisation by layer ("the views go in the view folder!") instead of organisation by module ("These things work and change together with a defined boundary"). You can have what you're asking for if you agree to a predefined architecture and everyone agrees to write code that way.
windlep 3y ago
This is how I use the tool the author created, Structurizr. I auto-generate the initial diagrams, then manually fix it to make it more readable. We then check-in the JSON workspace export into our git repo. The first two levels of the C4 model don't change regularly, so this isn't a frequent process to repeat.
learn_more 3y ago
Check out https://schematix.com/video/?play=schematix-editing https://schematix.com/video/?play=schematix-editing Schematix generates diagrams (models) from code which can be entered via the web interface, or from a remote command line or scripts. Diagrams are rendered on-the-fly from queries called "topological expressions" run against the model. The model must be updated as IT workers change the environment, but since diagrams are generated from code, they always reflect the most up to date information from the model.

falcor84 3y ago

I would actually be really interested in a bi-directional workflow, such that I would also be able to perform system redesign by changing the diagram's connections - the tooling will then automatically update the interface and the tests such that I wouldn't be able to commit my changes until the implementation matches the diagram.

Sophistifunk 3y ago
IMO the source code to aspects of the system that are best shown as graphs should be the graphs.
jakewins 3y ago
I realize this isn’t what you’re arguing for, but as a cautionary anecdote on this topic: Paul alludes to it in his post about Healthcare.gov from the other day, but this was apparently one of the major parts of the failure there - endless lines of code generated from UML diagrams, making reading the code hard and things like “can we add a trace statement here” difficult. Optimising for diagrams-as-source-of-truth has drawbacks for debugging and maintainability of the running code https://www.pauladamsmith.com/blog/2023/10/the-10-year-anniversary-of-the-healthcare.gov-rescue.html https://www.pauladamsmith.com/blog/2023/10/the-10-year-anniv...

bdg 3y ago

This requires a preset architecture standard that explains specifically what boxes and arrows are, and how boxes/arrows interact. Lots of software smears a logical box out over several folders in the code, sometimes even with entirely different names. I don't just mean people write non-cohesive code, I mean frameworks tend to prefer organisation by layer ("the views go in the view folder!") instead of organisation by module ("These things work and change together with a defined boundary"). You can have what you're asking for if you agree to a predefined architecture and everyone agrees to write code that way.

windlep 3y ago

This is how I use the tool the author created, Structurizr. I auto-generate the initial diagrams, then manually fix it to make it more readable. We then check-in the JSON workspace export into our git repo. The first two levels of the C4 model don't change regularly, so this isn't a frequent process to repeat.

learn_more 3y ago

Check out https://schematix.com/video/?play=schematix-editing https://schematix.com/video/?play=schematix-editing Schematix generates diagrams (models) from code which can be entered via the web interface, or from a remote command line or scripts. Diagrams are rendered on-the-fly from queries called "topological expressions" run against the model. The model must be updated as IT workers change the environment, but since diagrams are generated from code, they always reflect the most up to date information from the model.