Avoid headaches from creating diagrams — use PlantUML

Photo by Priscilla Du Preez on Unsplash

Using the typical design tools

In software development, Unified Modeling Language (UML) diagrams are such a crucial part of the design phase. But, using the typical design tools takes more time than you think, especially when there are a lot of review comments (been there). You have to think about other design stuff like spacing, alignments, styles, etc.

Using PlantUML

To avoid headaches, we used a tool called PlantUML. This tool allows us to easily create UML diagrams from simple text descriptions.

Open-source tool that uses simple textual descriptions to draw beautiful UML diagrams.

In this beginner’s guide, I’ll talk about the step-by-step process on how to use PlantUML with Visual Studio Code:

1. How to integrate PlantUML with VS Code
2. Writing UML diagrams
3. Exporting options
4. Conclusion

You can also checkout our youtube video guide here:

How to integrate PlantUML with VS Code

To integrate PlantUML with VS Code, all you have to do is install the PlantUML extension:

In VS code, search for PlantUML in the extensions tab and click install. You can also use the VS code command palette (CTRL + SHIFT + P) and type:

ext install plantuml

Writing UML diagrams

With PlantUML, we can create different types of UML diagrams such as sequence diagram, use-case diagram, class diagram, activity diagram and more. There is even an option to create a Gantt diagram!

To start, open a new file in VS code and save it as .puml or .plantuml (these are the common file extensions for PlantUML).

Then you can start writing UML diagrams. In this case, let’s create a simple sequence diagram:

VS Code lets you preview your PlantUML easily just by pressing ALT+D.

@startuml
actor "User" as user
participant "Home Page" as homepage
participant "Home API" as api
database "Database" as db
user -> homepage : Click Home button
homepage -> api : getHomeDetails()
api -> api : validateRequest()
api -> db : getHomeDetails()
db --> api : return result
api --> homepage : return result
homepage --> user : display result
@enduml

In this example, if you try to analyze the syntax, it is very easy to understand:

1. The @startuml and @enduml indicate the beginning and the end of the design.
2. The next part is to declare the entities involved in the sequence. You can indicate different entities such as an actor, participant, database, and more.
3. Then we added the interaction of the entities and it’s description. The arrow and dotted arrow syntax is used to draw the message between the two entities.

Note: other UML diagrams have different syntax and rules, but are still easy to understand.

Exporting options

You can export your diagram in different formats such as .png, .svg, .pdf and more.

To do that, just open the VS code command palette (CTRL + SHIFT + P) and type or choose:

PlantUML: Export Current Diagram

The default export directory is the same as your workspace folder. You can also click the View Report button and check the Output tab in VS Code to confirm where it is saved.

To change the output location:

1. go to VS Code File → Preferences → Settings
2. Search for plantuml
3. Update the Plantuml: Export Out Dir

Conclusion

PlantUML makes it easy for us software engineers. Creating diagrams with simple text descriptions makes us more efficient, and less headaches. Here are a few takeaways:

1. Easy to learn. The syntax is pretty basic and human readable. It doesn’t take too much time to learn.
2. Concentrate on logic. No need to drag and drop, resize and align objects.
3. Integrating with VS Code makes it much more productive. You can easily generate a preview while working on a diagram. Also, you can easily export with different file formats.
4. Easy to manage. Easily track and compare changes with a version control system like git.

I have covered the basics of PlantUML to get you started and there is so much more that can be done. Take a look at the docs for more information.

Hope this guide helps.

Thank you for reading!

We are Team Kodou, a group of passionate misfits that love sharing content and helping the world be a better place.

Please support us by also subscribing to our youtube.

If you are interested in merch, pls check out below. A portion of the profits will be donated to charity.

Click here for our merch

Kodou Merch