I like PlantUML and the whole diagrams-as-code ethos, where diagrams auto-generate from source code in the same repo.
Sure, the way PlantUML lays out objects and lines in free-form diagrams is arcane – try drawing anything beyond a few components, and you’ll end up in a pitched battle with the layout engine, resulting in a mediocre diagram in a state where you’re afraid to make changes, lest the lines and placement go all wonky (again).
Thankfully, things are better when using PlantUML to produce opinionated diagram types, where the layout rules are predetermined, such as sequence diagrams, mind maps etc.
I got to thinking – could I use PlantUML in the workplace, outside traditional architecture/code documentation, to help visualise other things? Only one thing for it – give it a go…
Is a picture really worth a thousand words? What if that picture was a diagram?
A colleague recently introduced me to Diagrams as Code, using PlantUML, and in this post we explore the concept of diagrams-as-code, and how to use PlantUML.
Let’s start with some background. Diagrams should engage their audience, informing them and encouraging collaboration. Understanding the knowledge and needs of your audience is critical to creating a successful diagram.
We adjust the diagram to suit the audience, using different views of people / process / technology to inform and engage them. Often, we will draw multiple views of the same system to suit the needs of different audiences, as per Figure 1.
(Note: copy of my original blog post from September 2016)
I recently went through the pain of configuring a Python project to automatically produce documentation on Read the Docs. While the outcome was good, the process getting there wasn’t… This blog is for those who want to avoid the steep learning curve I went through. Continue reading →