Documentation as Code for Cloud Using PlantUML

Documentation as Code for Cloud Using PlantUML(blog.dornea.nu)

96 points by cyneox 2 years ago | 34 comments

mikeholler 2 years ago |

One of the coolest things about plantuml is the generated PNG actually contains the source code for the image as metadata. If someone gives you an image, they don't also need to send you the source because you can extract it using the plantuml CLI.

Yasuraka 2 years ago | |

draw.io also supports this for .png and .html, so you can just import and continue editing it

Coworkers always accuse me of tomfoolery when I tell them it's already in there

siddharthgoel88 2 years ago | |

That is so cool. Did not know this. Thank you!

NicoJuicy 2 years ago | |

Didn't knew that! Thanks

animesh 2 years ago | |

I wonder if the Copy As Image also does this. I will check.

cyneox 2 years ago | |

This is indeed awesome! Thanks for letting us know.

jerieljan 2 years ago |

I love PlantUML. I was always fond of it in my early days as a software engineer and still use it today, along with all the various ways to draw diagrams out there, whether it's through a web tool like draw.io or Miro or through markup like PlantUML and Mermaid.

Some stuff I'd like to share with the rest:

- PlantUML's default style has improved since the days of red/brown borders, pale yellow boxes, drop shadows and such but I've attempted fixing it before through a preset style [I've made before here](https://gist.github.com/jerieljan/4c82515ff5f2b2e4dd5122d354...). It's obsolete nowadays, since I'm sure someone has made a style generator somewhere, and last I checked, PlantUML allows a monochrome style out of the box.

- [Eraser](https://app.eraser.io) is promising, considering that it's trying to blend both diagram-as-code markup along with the usual visual diagram editor. I'm still seeing if it's worth picking up since Miro's hard to beat.

- On an unrelated note, [WikiJS](https://js.wiki/) is a self-hosted wiki that happens to support draw.io, PlantUML and MermaidJS diagrams out of the box. Quite handy to have for your own docs.

- I use Miro nowadays since it's significantly quicker to draw things freeform and to collaborate live with folks on a whiteboard at the cost of having your diagrams in markup, but it's easy to miss the integration that [you can actually import PlantUML](https://help.miro.com/hc/en-us/articles/7004940386578) and Mermaid diagrams in a Miro board too. You can also do edits too, but it's on its own PlantUML section, of course.

_AzMoo 2 years ago | |

When I'm experimenting or working on something that is dynamic I'll use Miro (or FigJam now), but once I've locked it in I put it in PlantUML and commit it in the relevant repo. So handy for portable, normative docs.

thangalin 2 years ago |

My cross-platform desktop text editor, KeenWrite, allows users to define variables in an external YAML file. The editor calls out to Kroki[1] to convert text-based diagrams to SVG. The diagrams can reference variables and are rendered using EchoSVG[2].

KeenWrite[3] can produce PDF documentation from Markdown documents that has PlantUML diagrams with elements stored in an external, machine-readable file. Here are screenshots showing variables on the left, diagram text in the middle, and a real-time render on the right:

* https://raw.githubusercontent.com/DaveJarvis/KeenWrite/main/...

KeenWrite supports all diagrams offered by Kroki, which includes "diagram-plantuml".

[1]: https://kroki.io/

[2]: https://github.com/css4j/echosvg/

[3]: https://github.com/DaveJarvis/keenwrite

jimmcslim 2 years ago |

I'm a big fan of PlantUML. The only issue I have is that the layout algorithm sometimes can be challenging to work with for certain types of diagrams, although this is often due to there being too many nodes in the diagram... so, simplify it?

Nevertheless one improvement I would like to see for PlantUML (and similar tools like Mermaid) is a way to separate content and style from layout... i.e perhaps have a viewer that can pop up and let the user reorganise the elements and save the absolute positioning to a separate sidecar file?

smusamashah 2 years ago |

The list of many PlantUML kind of tools https://xosh.org/text-to-diagram/

bjt12345 2 years ago |

I use PlantUML to create quick network diagrams.

It's the only solution I found which allows tailoring a diagram if it renders poorly.

For example, if access switches are to be on the left, and trunk switches on the right, PlantUML is the only solution I found which adequately allows the user to add such constraints, via:

S1 --E-- S2

cgb_ 2 years ago | |

Hey, what style of diagram are you using for this? Deployment diagram? Do you have link to an example?

bjt12345 2 years ago | | |

Layout hints in legacy activity diagrams, from memory:

https://crashedmind.github.io/PlantUMLHitchhikersGuide/layou...

Can take compass coordinates from memory, in shorthand.

In Python, I pull a network topology from an API, then convert it to PlantUML, then edit a few arrows/lines so to point the right way, the entire topology adjusts accordingly, and generally I arrive at a useable diagram very quickly.

Way quicker than Visio, and nothing else seems to be able to do this (e.g. graphviz doesn't allow this).

bluejekyll 2 years ago |

I started using plantuml more rigorously at work. I've found that collaboration on the drawings/diagrams, is simpler and easier as it can be tracked in Git. One additional thing that I've been using as well is the mdBook plugin to embed and render the images as part of a larger book. This has been helpful for large systems when there are many teams involved. We publish the content as github pages on the repos as well.

I'd like to start doing this with my open-source as well.

https://github.com/sytsereitsma/mdbook-plantuml

politelemon 2 years ago | |

We haven't found the same to be true. The moment there's an extra step involved in rendering the image, the advantages have been lost through numerous outdated copies. We found that people relied on the imagery more than the DSL behind it.

We now publish draw.io SVGs. GitHub renders them and people view them. The rendering engine is effectively the browser which makes it very accessible.

I suppose this means our companies have differing cultures or some other factor I'm not aware of

riffraff 2 years ago | | |

GitHub supports mermaidjs natively.

I prefer plantuml but mermaid is nice enough.

s1291 2 years ago |

Community list of comparisons between Text to Diagram tools: https://text-to-diagram.com/

afruitpie 2 years ago | |

It’s worth noting that this page is made by the makers of D2 (they mention it at the bottom, it’s no secret).

For me, D2’s syntax is the easiest to write, but it outputs sparse diagrams that are difficult to read without a lot of zooming.

lxe 2 years ago |

Somewhat related thing I've discovered recently that I'm finding tremendously useful: ChatGPT knows plantUML so it can generate amazing diagrams just from your prompt.

nextaccountic 2 years ago |

Here's three interesting Rust projects that use plantuml

You can embed plantuml and drawio diagrams in Rust doc comments and have it rendered in the docs, using this crate

https://crates.io/crates/rsdoc

And you can generate plantuml from SQL tables using

https://crates.io/crates/sqlant (this one is a rust port of a go tool, https://github.com/achiku/planter)

And you can embed plantuml in mdbook

https://crates.io/crates/mdbook-plantuml

pachico 2 years ago |

I have been using plantuml with Aws icons for years, already. I love it. I can write locally, in gitlab and in Confluence. I can iterate over it and it says right embedded in my docs.

gatane 2 years ago |

I used PlantUML for a lab project. I would recommend getting the latest jar version, it has support for themes and a lot of other stuff!

pagnol 2 years ago |

For anyone using Emacs Org mode, it may be interesting to know that plantUML diagrams can be embedded in Org documents using Babel.

cyneox 2 years ago | |

I've used ORG along with Babel to write that post: https://github.com/dorneanu/roam/blob/main/org/blog/2023-07-...

candiddevmike 2 years ago |

What does PlantUML do better than mermaid?

cratermoon 2 years ago | |

PlantUML is a command-line tool to generate diagrams in multiple formats that can be saved and shared, it also has a GUI. Mermaid is a javascript library for rendering simple text definitions to useful diagrams in the browser, although there is a separate command line tool. It has chromium as a dependency.

Last I heard, PlantUML has support for more types of diagrams, allows for themes and more customization.

MilStdJunkie 2 years ago | |

Lots more chart types, or at least chart types that aren't found anywhere else. JSON render, SALT UI markup, regex diagram, a YAML renderer. That said, Mermaid also has some unique diagrams, like the fantastic git renderer. And it runs on JS only. So Mermaid has probably got longer legs, while stuff like PlantUML and Vega/Vega-Lite taking on more edge cases.

s1291 2 years ago | |

For a comparison between different Text to Diagram tools, see: https://text-to-diagram.com/

rowanG077 2 years ago | |

Well not having chromium as a dependency is a start. But even glossing over that fact I found that it's much better for many diagrams. PlantUML is also a one stop shop. You can basically make anything kind of diagram in it.

anticodon 2 years ago | | |

> Well not having chromium as a dependency is a start.

Java as a dependency is not much better. It's also huge which is important if you build your diagrams in containers and/or CI/CD. It's also very slow to start. I'm always surprised when benchmarks show that Java is "fast", because it's so huge and has atrocious cold start time, that makes it very unpleasant to use for CLI utilities.

rpz 2 years ago |

similieHash(“documentation as code”) == similieHash(“nails as hammer”)