Improving Design Communication with PlantUML
I guess when it comes to software engineering, code is usually the arbiter of truth, although it isn’t always the best avenue for communicating a design for your average person/laymen considering developers and computers can parse through lines of code like it’s nothing- but trying to understand the higher-level structure or interactions within a system can be somewhat challenging without some kind of abstraction to it, which is why UML diagrams have a great deal of utility to them as they strip-away the low-level implementation details that the layperson in question doesn’t have to deal with- allowing us to focus on the essential interactions.

Why I chose this?

So for this week’s professional development blog, i decided to go with this resource regarding UML diagrams(https://miro.com/diagramming/what-is-plantuml/#what-is-plantuml) considering we’ve been working on this in class for the better part of a few class days now. While syntax is important, I wanted a resource that went beyond the basics and emphasized best practices — specifically, how to make diagrams more readable and effective as communication tools. Which ties back to what we were doing for the classwork activity, the learning objectives of the activity we did in-class together includes identifying parts of UML diagrams, being able to connect them to Java implementation or even being able to draw the diagrams using Markdown with PlantUML.

What did I learn?
The article did help me with solidifying my understanding of the lifelines, the messages and the activation bars within the UML sequence diagrams, but in general from the article, i learned how PlantUML treats diagrams as code: by writing simple text scripts, you can generate UML diagrams consistently and efficiently. This can help out somewhat in collaborative environments, where diagrams kind of have to evolve along with the codebase. The section on best practices i think i find the most interesting since the article highlights that diagrams should focus on clarity over completeness.

For example, a UML sequence diagram should emphasize the key messages between objects rather than every small detail. The guide also pointed out how to use colors, notes, and layout to improve readability — some things that you don’t really pay too much attention to(at least for myself) so them giving pointers on how to use those things is good in case we want to make things look more pretty or neat-looking. I do appreciate the explanation of how PlantUML integrates with version control systems although it’s not something i found particularly too significant. Since diagrams are stored as text, they can be tracked and managed in Git just like source code. This makes them much easier to update collaboratively if need be, compared to traditional tools where diagrams are static images.

Reflection and Application?

At first i thought it might be something i’d forget about in a month or two(if i’m being just honest with the article), i do think it helped with reinforcing the core concept that the UML designs aren’t just academic exercises that we were doing in class, but it can be a practical tool for teams collaborating with each other compared to the traditional tools where it’s like the diagrams are just static images alongside the fact that it isn’t just checking a box but being able to make sure everyone understands, between the code and the people. I guess i’d say for any future projects that come to mind, i’ll apply what i’ve learned by keeping my diagrams somewhat simple and try to make it with an audience in mind since there will be people i’ll interact with and get feedback when it comes to my PlantUML code. I also wouldn’t mind experimenting with Markdown and Git so that the diagrams can evolve with the codebase, becoming almost like living documents as opposed to a static artifact.

From the blog CS@Worcester – CSTips by Jamaal Gedeon and used with permission of the author. All other rights reserved by the author.