The Hitchhiker’s Guide to PlantUML

The Hitchhiker’s Guide to PlantUML(crashedmind.github.io)

150 points by bambambazooka 5 years ago | 31 comments

mdaniel 5 years ago |

A hidden gem in the about page:

which appears to be harvested from GitHub searches: https://github.com/yfuruyama/real-world-plantuml/blob/master...

For those unfamiliar with it, PlantUML enables you to create many types of diagrams (both UML and Visio-like) using code. Quick overview here: https://crashedmind.github.io/PlantUMLHitchhikersGuide/about...

vasergen 5 years ago |

I like plantUML, I really do. but I think more people will be attracted by it, if they improve design and colors, so it looks modern out of box without any hacking

grmartin 5 years ago | |

I was originally a proponent of it, but I find these days i prefer Mermaid. It doesnt hurt that there are more Markdown editors/viewers integrated with Mermaid than PlantUML.

octygen 5 years ago | | |

Until mermaid comes up with the vast list of diagrams one can create in Plant UML, I don't see it as operating in the same weight class. E.g., wireframes, basic Gantts, AWS diagrams, component diagrams with graphviz (thought I confess I hate this dependency), archimate diagrams if you're really hardcore.

emmelaich 5 years ago | | |

I hadn't heard of Mermaid. Looks good!

https://mermaid-js.github.io/mermaid/#/

octygen 5 years ago | |

You could customize a style for your diagrams and then include it via a one-liner in every diagram you create. This also allows for branding of diagrams.

Personally, I'm a huge fan of the simplicity and whenever I present such a diagram to teams or execs, I break the ice by warning them it'll be "ugly" or "let's go back to 1995 for a sec" :) More importantly, the focus remains strictly on the content because of the basic design.

lallysingh 5 years ago | |

They're working on it! https://plantuml.com/style-evolution

deeviant 5 years ago | |

Yeah, it's output looks like a 1995 era website.

bauerd 5 years ago |

>It has a simple intuitive syntax

The code example reminds me of Latex: https://crashedmind.github.io/PlantUMLHitchhikersGuide/Netwo...

_ZeD_ 5 years ago | |

It's not so bad. What do you propose instead?

cosmojg 5 years ago | | |

I think OP meant that as a compliment, not a criticism.

mintyc 5 years ago |

PlantUML has morphed into a two part tool. Its original purpose was to visualise various forms of UML diagrams.

More recently it has utilised its underlying graphviz to create a more general 'graphviz on steroids' diagramming tool (referred to as the PlantUML standard library).

The original UML diagrams can be styled to look modern, but normally are shown in a default slightly old-fashioned and uninspiring visual style. Such a shame if that's your impression.

As mdaniel posted, just a refresh of the colour scheme can modernise the look of UML diagrams

https://real-world-plantuml.com/umls/4831648155697152

The second part covered by this hitchhikers guide shows a modern take on visualising component relationships.

Both parts allow visualisation as code, but otherwise have different purposes.

I wish we'd see more UML examples in a modern style.

(I'd also recommend MarkDeep for documentation. Includes these + markdown, math, doxygen integration and more)

dang 5 years ago |

If curious see also:

https://news.ycombinator.com/item?id=21426793

majkinetor 5 years ago |

PlantUML is simply awesome. There is no other langauge that supports so many diagramming features. I use it for more then half decade now on all projects. You can create interface mocks, timelines, mindmaps, gant charts, uml diagrams, graphs, OOP diagrams, whatever really, if it was invented, it is in plantUML for sure, or will be. Also, devs are VERY responsive, if you have a good idea, they will for sure implement it.

The only thing that is going on my nerves sometimes is that you can't preciselly say position of elements and being happy with how concrete, albeit more complex diagram draws, is somewhat trial and error (you change direction, change arrow length here and there, change element order etc) but eventually you will make it likeable.

Other thing is that syntax differs a lot between diagrams and I always need to check out manual, no matter how much I use it, it just doesn't stick for me. Thankfully, this is all very easy to do.

For those on Windows, I created chocolatey package [1] that installs all dependencies along with PDF manual and you can have it on your CI or local server as simply as `cinst plantuml`. There is also vscode and mkdocs plugins that are great so you can just insert plantuml diagram strait into markdown between other documentation (alternative is to prerender images which I also did in the past, and is very fast as plantuml regenerates only changed stuff). If you need mkdocs bundled with all this and other nice stuff, check out mm-docs [2].

I must honestly say that this is one of the best FOSS projects I encountered and that it definitelly needs more recognition and support.

[1]: https://github.com/majkinetor/au-packages/tree/master/plantu...

[2]:https://github.com/majkinetor/mm-docs-template

robador 5 years ago |

Can someone explain the difference with graphviz?

samatman 5 years ago | |

graphviz makes graphs, and PlantUML makes UML diagrams:

https://en.wikipedia.org/wiki/Unified_Modeling_Language

Not being flippant, that's the difference. graphviz/dot is general-purpose and can be configured to produce UML-like diagrams, but that's labor intensive.

PlantUML takes text and produces UML diagrams from it. It's configurable... as long as you want UML. If you want something else, reach for graphviz.

In my own work, I use dot/graphviz for diagramming abstract syntax trees, while I've used PlantUML a couple times to diagram the layout of structs and to map the high-level relationships between modules in large software projects.

org-mode does a very nice job of integrating both of those formats into documents, fyi.

zmmmmm 5 years ago | | |

Putting the emphasis on UML is a bit misleading actually (even though it is literally in the name of the tool). I use it for basically any kind of ad hoc diagramming. Essentially, an equivalent of Markdown for PowerPoint charts if that makes sense. A few quick lines in text that look mostly like what they come out as in the diagram and you have a very nice representation of a workflow etc.

dschuessler 5 years ago | | |

In fact PlantUML uses graphviz under the hood.

rjsw 5 years ago | | |

> as long as you want UML

... as long as you want UML diagrams.

It can't save out valid UML class definitions to a file.

Kuinox 5 years ago | |

PlantUML use graphviz. PlantUML create UML diagram, where graphviz only display graphs.

octygen 5 years ago | |

Graphviz organizes the elements in a graph in the most efficient way possible.

Plant UML uses graphviz as a library to generate a variety of component diagrams.

a_c 5 years ago |

Sort of tangential. While there are lots of tools to convert code into diagram, I wonder if there are tools to convert diagram into code with defined rules.

Am asking because there are lots of programming illiterate colleagues. By encoding the business rules into drawing rules, one could potentially delegate the business logic writing part to non-coding staff

dtheodor 5 years ago | |

There's a whole discipline around converting diagrams to code, called Model Driven Engineering. The idea is that you capture business entities and rules in various well defined diagrams, which then can be converted to code through code generation tools, i.e. can be turned into programs.

This was mainly promoted and developed by the creators of UML and has strong ties to it. That was UML's vision after all, a visual diagram language that unambiguously captures the essense of a program.

The Eclipse Modeling Framework is a framework that implements this approach.

I think MDE was up and coming around the end of the 2000s. As far as I know it didn't really go anywhere.

rcfox 5 years ago | |

You could perhaps do something with the dot language and gvpr[1]. It's not super easy to use though, but I've used it to generate a Javascript representation of a graph before.

[1] https://manpages.debian.org/testing/graphviz/gvpr.1.en.html

mch82 5 years ago | |

webgme.org, with a fair amount of work

a_c 5 years ago | | |

Thanks for the pointer! Will check it out

csours 5 years ago |

It took 3 clicks to get to the code. https://crashedmind.github.io/PlantUMLHitchhikersGuide/Netwo...

mdaniel 5 years ago | |

Did you mean _code_ like https://github.com/Crashedmind/PlantUMLHitchhikersGuide (which appears to be just the generated code from https://github.com/Crashedmind/PlayingWithPlantUMLSource for some reason)

csours 5 years ago | | |

No, I meant the UML words instead of UML pictures.