c4-notation VS Pythonocc-nodes-for-Ryven

Second this.

Reference for anyone looking I to it: https://c4model.com/

There is also quite a lot of options for helping create these diagrams. I've found https://structurizr.com/ to be the best of what I've tried so far.

What you are describing sounds a lot like C4: https://c4model.com/

The C4 model [0] provides a mostly sensible structure and techniques for representing pure software systems across different abstraction levels.

For systems involving software and hardware, or other complex interfacing (both technology and bureaucracy) this starts to delve into the universe of systems engineering. There's a decent assembly of knowledge on that in the SEBoK [1].

As another commenter has already called out too, one of the most valuable sources of information is also _why_ a system is in its current form and _how_ that's changed over time. ADR's [2] really do a good job at nailing this for just about any scale.

[0]: https://c4model.com

[1]: https://sebokwiki.org

[2]: https://adr.github.io

There a various standards for documenting software architecture, like arc42 or C4. While useful and somewhat well-known (there is certainly a correlation here), here architecture documentation can be further simplified, particularly due to the self-similarity of project and component. Following is a small template, that can also serve as a project's and component's README:

I would suggest that if your architecture diagrams are a bunch of icons provided by AWS/Azure/GCP with lines pointing at each other... you are doing it wrong.

The 'what does this box do for my system' is vastly more important than the 'which in vogue offering from my cloud provider implements it'.

I highly suggest folks take a look at the C4 Model: https://c4model.com/

We often use abstractions in software engineering to communicate complex architectures and software systems. In this article, we’ll discuss how abstractions are inherently hierarchical and how the C4 model provides a nested structure for defining your software architecture. We’ll then cover how IcePanel allows you to create interactive and zoomable diagrams for your audience to zoom in and out of different levels of technical detail.

You probably want https://c4model.com/ which explains what a C4 architecture diagram is. (See the first footnote in the article.)

As a visual person (traditionally trained as a graphic artist), I've wanted this sort of thing for a long while, and I've been trying to use it for 3D.

Surprisingly, there are multiple specialized tools for this:

- https://www.blockscad3d.com --- an adaptation of Google's Blockly to OpenSCAD

- https://github.com/derkork/openscad-graph-editor --- wires and nodes, it has the advantage of exposing _all_ of OpenSCAD's commands (the above has a subset)

- https://github.com/Tanneguydv/Pythonocc-nodes-for-Ryven --- a module for using PythonOCC in Ryven --- when I finally succeeded, I found the language inscrutable, even when provided w/ quite nice examples (definitely a failing on my part, not that of the tool)

- https://github.com/graphscad/graphscad --- it took a long while for the source code for this to be made available, and for a while it had compatibility problems (why was "cube" redefined?) --- probably defunct for political reasons, it had some interesting ideas, in particular the ability to have custom icons for modules

- https://www.nodebox.net --- if memory serves I got hung up by not easily being able to do 3D, and when doing 2D having precision problems (or maybe that was Processing.org)

and I've been using these tools to make various things:

https://willadams.gitbook.io/design-into-3d/3d-project

(and maybe eventually I'll finish something)

The problem I've been running into is there doesn't seem to be an answer to the question:

"What does an algorithm look like?"

I recently had occasion to mention Herman Hesse's _The Glass Bead Game_ (also published as _Magister Ludi_) and I'll bring it up again --- what is a meaningful graphical representation of a program?

The Drakon folks argued that there should be one true path but that's not really communicative and I would note that if this was a simple thing it wouldn't be decades since I last saw a physical Flowcharting Template:

https://americanhistory.si.edu/collections/object-groups/flo...

(and it's pretty rare to even see a well-done electronic drawing of a flowchart since Visio made its splash and vanished into the bowels of Microsoft)

The main problem seems to be one of expressiveness not scaling up well, hence:

https://blueprintsfromhell.tumblr.com/

https://scriptsofanotherdimension.tumblr.com/

Presumably, one doesn't want to define modules/variables unnecessarily --- but the question becomes where is that boundary?

If you define too many, then you're back to the "wall of text" which one was trying to avoid (but wrapped up in nice boxes with some lines or shapes), and if one doesn't use them (well, look at the pretty/awful images in the links above).

Ideally, a well-coded visual program would have a pleasing aesthetic appearance which is expressive and communicates flow and function, and I've tried for that at:

https://willadams.gitbook.io/design-into-3d/programming

(though I wish that there was an easy way to export an SVG version of a program)

I believe that what is needed here is some graphical equivalent to Literate Programming: http://literateprogramming.com

Is there a nice GUI toolkit integration which would allow making a graphical application with this? I have an idea I want to try it which might be a good fit.

"What does an algorithm look like?"

I'm an intensely visual person, but have never found a visual programming system which scales well --- the problem is, past a certain level of complexity one has to use modules, which then devolves the visual representation down to just a bunch named blocks.

That said, I'm using BlockSCAD:

https://www.blockscad3d.com/community/projects/1421975

to work up designs which I'm then putting into other tools.

Looking at GraphSCAD:

http://graphscad.blogspot.com

and there's also Ryven and pythonocc which I managed to get installed:

https://ryven.org

https://github.com/Tanneguydv/Pythonocc-nodes-for-Ryven

but I'd really like to see a tool for this sort of thing which made G-code.