Documentation as Code for Cloud Using PlantUML • Hacker News Board

Re: Documentation as Code for Cloud Using PlantUML

#21

Post by anticodon » Mon, Jul 31, 2023, 5:30 AM UTC

rowanG077 wrote: post #11

candiddevmike wrote: post #7

What does PlantUML do better than mermaid?

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.

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

Re: Documentation as Code for Cloud Using PlantUML

#22

Post by pagnol » Mon, Jul 31, 2023, 5:57 AM UTC

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

Re: Documentation as Code for Cloud Using PlantUML

#23

Post by riffraff » Mon, Jul 31, 2023, 6:48 AM UTC

politelemon wrote: post #5

bluejekyll wrote: post #4

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…

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 comp…

GitHub supports mermaidjs natively.

I prefer plantuml but mermaid is nice enough.

Re: Documentation as Code for Cloud Using PlantUML

#24

Post by cgb_ » Mon, Jul 31, 2023, 6:58 AM UTC

bjt12345 wrote: post #15

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

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

Re: Documentation as Code for Cloud Using PlantUML

#25

Post by nextaccountic » Mon, Jul 31, 2023, 7:02 AM UTC

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

Re: Documentation as Code for Cloud Using PlantUML

#26

Post by zokier » Mon, Jul 31, 2023, 7:37 AM UTC

anticodon wrote: post #21

rowanG077 wrote: post #11

Earlier quoted context omitted.

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.

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

If you are super concerned about startup times, you could run plantuml as web service instead, then your renders are just a single http call away

https://github.com/plantuml/plantuml-server

Re: Documentation as Code for Cloud Using PlantUML

#27

Post by animesh » Mon, Jul 31, 2023, 8:02 AM UTC

mikeholler wrote: post #2

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.

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

Re: Documentation as Code for Cloud Using PlantUML

#28

Post by thangalin » Mon, Jul 31, 2023, 8:48 AM UTC

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

Re: Documentation as Code for Cloud Using PlantUML

#29

Post by rowanG077 » Mon, Jul 31, 2023, 9:14 AM UTC

anticodon wrote: post #21

rowanG077 wrote: post #11

Earlier quoted context omitted.

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.

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

The big difference here is that chromium is an end user application. Java is designed to be a dependency. In fact java only goal in life is as a dependency.

Re: Documentation as Code for Cloud Using PlantUML

#30

Post by _AzMoo » Mon, Jul 31, 2023, 11:23 AM UTC

jerieljan wrote: post #17

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…

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.