> NOTE: It does not control any actual cloud resources nor does it generate cloud formation or terraform code.
would be kinda cool if it could, though
I can see the point of DSLs where the output is used by other code (e.g. builder pattern, LINQ). But this seems like overhead compared with the alternative?
Or a screenplay?
(Because there are better formats for them)
Vs. Cooking or Writing which aren't coding practices unto themselves.
Screenplays... are already written in code, partly. If they weren't, they'd include quotation marks and "she said" after every line.
Yaml isn't really code in the same sense as python is, and Shakespeare didn't write in code in the same sense that the diagrams in this article are.
The other thing you list, input, is optional. I write programs that don't take any input all the time. Monte Carlo simulation, for example. The entire demoscene is largely devoted to creating incredibly sophisticated programs that don't take any input. Postscript is a full, Turing-complete language whose primary purpose is to create programs that generally don't take any input
Nice and simple, but unfortunately you lose all accessibility with a .png diagram. Specifically, they're impenetrable to screen readers.
Do you know if there is anything similar for screen readers?
DaC seems nicer for infra
If you're using GitHub it's supported in any markdown file, and therefore accessible to any other dev with repo access. No permissions issues, edits can go through code review, and no dependencies necessary.
LLM's are well-trained on Mermaid. Gemini specifically is fantastic as a 'diagram assistant'. I was able to create this diagram and a ton of other such diagrams quite easily with Gemini and Mermaid's live editor: https://nshkr.com/SecureSphere-Overview-20241102.png
The VSCode Mermaid plugin and the GH integration make this very simple to do.
https://code.visualstudio.com/updates/v1_95#_mermaid-diagram...
https://code.visualstudio.com/updates/v1_95#_mermaid-diagram...
Allowing specification in Python offers very little advantage - in theory you think, hey, I've got hi-lighting, autocompletion, and so on from an IDE. It'll play nice in VCS. Maybe I can interrogate orchestration layers and so on to produce dynamic views.
In practice diagrams are produced by folks who might not want to use or learn python [or golang, their other implementation]. Instead a lean purpose-build DSL, maybe even an extension of graphviz dot, is easier and more portable for some audiences to pick up. Secondly, we can't JUST graft a DSL front-end onto these tools because the styled components are baked into the project.
My personal experience with layout engines is that they work OK for very small architecture diagrams, but become ugly or inelegant at useful scales.
I (and the teams I've worked with) settle on draw.io, either the desktop app, or committed as part of confluence, as the best way to describe intent/design - and rendering graphviz with a style up top for anything dynamic.
Would welcome seeing a true extension to the dot language that can unlock reasoning engines (like to do threat modeling) and render-time styling.
This is so absolutely ludicrously absurdly wrong that it's comical.
No one wants to learn a new programming language. Cf. all of the old algol languages that are still around and all their "replacements" that are no longer around.
Some people (not even a majority) are willing to learn a new language if compelled by force or incentive. Diagramming is absolutely not enough incentive to learn a new language.
Diagrams are a visual thing. I prefer a visual designer. I can send that to some random nontechnical person for a presentation and they can edit them, etc.
I find with things like this, it works pretty well until you want to do something off the beaten path, then it's a pain where you're trying to figure out how to get it to render like you want it to.
Reminds me of the ole "just move it 2px to the right" in the CSS of yesteryear
Quite the hyperbole, but I do agree that python isn't so wrong of a choice, but the problem is diagrams eventually interact with non-technical people and that's where it gets tricky.
I LOVE mermaid, d2, but at somepoint I hand the diagrams off to someone who knows nothing about markdown and honestly they shouldn't have to know it to interact with a diagram.
All these "diagrams as code" are great for an isolated group. I can pump them out WAY faster than manual drawing programs (draw.io, etc), but then run into the iterop wall w/ other teams.
I'd LOVE a place that could be like AWS's graphical editor that sort of goes in between the two. It's a hard problem I 100% agree and would require yet another DSL, ugh.
People who don't want to learn a new special purpose language are basically saying that 'I've got a hammer and everything is a nail' is fine, which is (to your point) absurd. Languages are tools, use tools to solve problems the tools were designed to solve.
Where I do agree is what you haven't said clearly: it isn't obvious what problems 'diagrams as code' solve. The idea is cool and I've used plantuml with some success, but in the end the diagram is supposed to be consumed visually (including changes - to preserve spatial relationships between versions).
Then, I discovered excalidraw[1]: it lets me sketch like lucid, but isn't nearly as polished or robust: you can throw together simple shapes, draw lines between them, and the lines stick to the shapes, so you can move them around and the lines move too. You can also group things together, and draw freehand, and also include text -- what more do you need?
The cool thing about excalidraw is that you can share your drawings, and export them as SVG files -- yay! I can version them again. You can also self-host it, which is a massive plus in my book.
/rant
Another thing these types of tools bring is multiplayer support. Which I found my distributed teams really benefiting from over time.
I’ve finally found a happy middle at work where I version control the markdown based “user manual” and API specs/docs, but the design pages, rich with graphs and diagrams are going to live on the corporate wiki and require that I just learn to be disciplined to keep them up to date.
Surely I can just do that and not everything has to be… I dunno what to call it… that thing where us programmers love to see every human process problem as requiring a technical solution.
However depending on how the resulting SVG looks like this may not be different than just putting a PNG into a git repo
Particularly in the latter cases, most of these tools embed the machine readable diagram inside of the PNG. So you can just open the PNG inside of draw.io or excalidraw (if it was created by that tool) and edit the diagram. This is because the plain text file is embedded.
It’s great that lots of tools are going this way. Notably, if you’re doing image generation with Stable Diffusion or Flux, you can just drag a PNG from ComfyUI into the ComfyUI window and get the same whole workflow. It’s a great learning tool.
As for diffs? Well, that’s hard - even if you were diffing the “source” text files for excalidraw or plantUML, a lot can change that makes it nearly impossible to understand. When all that really happened might’ve been a small styling change and moving a node.
Hold the phone -- some PNG files have plain text representations embedded within? That's nuts, I had no idea!
Hmm, and also a super convenient exfiltration format… never thought of that.
Out of curiosity, does anyone know of a drawing tool -- like Excalidraw, Lucid or Draw.io -- that has the option of exporting diagrams to code, i.e. something like PlantUML or Mermaid?
That is the point of diagrams as code. You focus on the semantics, not on what it will look like and you let the tool decide for you.
Sure it’s probably not worth learning python for, but it is a python library, it’s for pythonistas, not everyone.
Has a graph query capability which is like a reasoning engine. And beyond that, can run simulations on the models.
Multi user, version control with branch and merge, time shifting, etc.
It's for diagramming whole environments, not just discrete diagrams.
Bonus points it's running via Python, which gives me a reason to fire it up and kill two birds with one stone (I'm a PowerShell junkie, so my relationship to Python thus far has been "reluctantly professional").
Repeating my comment from that thread:
from diagrams import Diagram
from diagrams.aws.compute import EC2
with Diagram("Simple Diagram"):
EC2("web")
This pattern when implemented with context vars in the context managers is a pretty nice way to reduce the boilerplate, without the downsides of traditional globals. The state can be safely contained to just the with block.
Usually these types of APIs also allow usage without it, using the context vars only to populate arguments not explicitly provided.
It would feel a lot better if it was this, for example, where you use each context explicitly:
from diagrams import Diagram
from diagrams.aws.compute import EC2
with Diagram("Simple Diagram") as d:
d.add(EC2("web"))
from diagrams import Diagram
from diagrams.aws.compute import EC2
d = Diagram("Simple Diagram")
d.add(EC2("web")) d.add(first)
d.add(second)
d.add(...)
It is stack-based (which might delight Forth fans), but it excels at drawing and diagrams.
Ghostscript is a free PostScript interpreter: https://www.ghostscript.com/
https://www.learnmetapost.com/
that said, even MP wasn't friendly enough, hence the development of other options such as PGF and TikZ.
The phrase "A as B" tends to imply that "A" came temporally and causally first, then "B" was generated from "A" somehow. "B" is some kind of view, summary or transform of "A".
So I read "diagram as code", as that we have a diagram, and we are going to interpret it as code. We start with a diagram, and get code. A lot of visual programming type projects are in fact, diagrams as code.
Similar to the traditional text as (isomorphic to the) code (it is transformed into).
But "code as diagram", is what we have here. We are viewing the code, which came first, as a diagram which summarizes it. In a lossy but useful way. The diagram cannot be executed, so there is no diagram (acting) as code.
https://github.com/netbox-community/netbox
> NetBox functions as the source of truth for your network infrastructure. Its job is to define and validate the intended state of all network components and resources. NetBox does not interact with network nodes directly.. This separation of duties enables the construction of a robust yet flexible automation system.
https://github.com/netbox-community/devicetype-library
> Each file represents a discrete physical device type (e.g. make and model). These definitions can be loaded into NetBox instead of creating new device type definitions manually.
https://github.com/Abulhallaj/netbox-deviceimage
> Device images in PNG format and arranged by manufacturer. Each file represents front and rear of a physical device type (e.g. make and model). These images [based on vendor visio stencils] can be loaded into NetBox to obviate the need to create device images.
It has a VSCode plugin also > https://github.com/terrastruct/d2-vscode
* it's text-based
* it can generate animations. (Step 1, step 2... on separate slides)
Can anybody explain if this works if we are creating multiple diagrams in a web app?
https://github.com/mingrammer/diagrams/blob/master/diagrams/...
stack install diagrams-braille brldia -w 120 clock $(date +%H) $(date +%M) brldia -w 120 hilbert 4
The problem is that a picture really is worth a 1,000 words.
If the picture is going to be worth including, then the picture is probably worth a KB of typing. That’s a lot and can go horribly wrong - esp for what is basically a whiteboard diagram
Don’t get me wrong - graphviz for showing relationships between modules in a project, matplotlib for pretty much anything and “real maths graphs” - that’s all vital but is a different skill set and different intention to this kind of whiteboard but in code.
I think sometimes we have to admit, just draw the darn thing and take a photo.
I've no idea why people do not spend time in getting it looking good
Bonus points: an interface where you enter your diagram code and where a random set of 9 renders is shown with a different rendering rule added. You can go through this step multiple times by just clicking the diagram you think looks best. After a couple of iterations you have a diagram that is fairly fixed (avoiding the complete re-render problem when making changes) and beautiful.
Bonus points 2: make it also an editor where you can configure these rules in the GUI. When changing the rules in the diagram this is reflected in the 'view' part of the code.
My colleagues however like the idea but don't want to learn the syntax.
So I build a simple add-on to our internal mail system that, when invoked, scrapes the email and runs it against a fine tuned Llama 3.1 8b model which then generates a PlantUML diagram from natural language.
If the input isn't of an appropriate nature to be converted to a diagram or vague it will not do this.
What I have found is that now at least 50% of the team have used this feature once since go-live.
In many cases not all though, the immediately returned image is not 100% correct but there is a nice integrated way to edit and render which is now causing many to get familiar with the syntax whereas before they couldn't be bothered.
Overall it's been a nice, relatively cheap way to get GenAI to actually help us at work.
For that reason, we use a self-hosted instance at work to retain privacy.
I’m having trouble visualising how an email could be represented as a diagram.
So like many other orgs we use email heavily to get stuff done.
Like many orgs we have numerous teams that are required to co-ordinate together to get this stuff done.
A lot of the time there is some sequencing to the actions that needs to happen by these teams in a certain way to ensure we get this stuff done properly if at all.
So many emails could be interpreted like workflows ... A needs to validate with B then provide to C who then has to get confirmation from D.
There are more emails than I thought where something like PlantUML can help peoples understanding of the situation and also surface up potential areas of disagreement or misalignment quicker and also sometimes emails get so long that new entrants to the chain (via cc) would benefit from a quick visual summary.
For more complex diagrams, where explainer notes are beneficial, I find hand tweaked diagrams can not be beaten (my go to is draw.io)
If a simple DaC diagram is 1000 words, then a hand tweaked diagram is 10,000. And that 10,000 pays off. The bang for buck payoff is there. Of course, other considerations like maintainability etc etc
- PGF/TikZ
- PGFPlots (building on the above)
- PSTricks
- AsymptoteI heard that likec4.dev is a good alternative for this, but I have no hands on experience with it.
For example, at $work we use Confluence for documentation - I just don't see any of the solutions mentioned in this thread as being compatible with deploying diagrams to confluence, or indeed any type of CMS. It seems that at a minimum you need some bespoke docs rendering pipeline in every repository which spits our rendered docs and diagrams to some other platform?
How does everyone else solve this?
http://literateprogramming.com/
getting folks to actually use that is a totally different problem. I've been using a custom .sty file to do this in a native fashion: https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... so that the source isn't a sea of grey comments: https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... but it's early days yet, and the project is niche and my coding style quite prosaic.
Failing that, a good build system might help. Like I'm sure you could rig Bazel or even Make to regenerate the PNG/SVG when the input changes.
Then your code is a mess and the results are fragile.
I'd love to find a diagram as code software that works well, but unfortunately PlantUML, Mermaid, D2 have all had the same issues
>What does an algorithm look like?
The problem is expressiveness of such a diagram is bounded by the size of a screen or a sheet of paper, and once one starts to scroll, or can't see the entire flow at a glance, things get complicated.
The node/wire programming folks have this a bit rougher to the point that there are sites such as:
https://blueprintsfromhell.tumblr.com/
https://scriptsofanotherdimension.tumblr.com/
I prefer to work visually, but not sure if that's actually valid --- unfortunately https://www.blockscad3d.com/editor/ doesn't support all of OpenSCAD and https://github.com/derkork/openscad-graph-editor has problems with a stylus (I have to leave the Windows Settings app open to toggle stylus behaviour which is enough friction that I don't use it as much as I would otherwise).
There are promising tools though: https://nodezator.com/ and https://ryven.org/ are very cool.
With some quick playing around, I don't see a way to parameterize is. Ie. If I want to show a different amount of workers in your example[1] if I am creating a dev or prod diagram. It would be really nice to be able pre-define certain parts of the diagram and add as desired.
https://diagrams.mingrammer.com/docs/getting-started/example...
If the obvious way is what you tried then yeah, the library should be changed to support this.