Collaborate effectively using PlantUML for Software Engineers

Photo by ThisisEngineering RAEng on Unsplash

Now more than ever we need to be able to communicate and collaborate effectively — working from home is our (temporary?) normal at the moment, and we need to be sure that our messages are delivered correctly.

The days of tapping a few people on the shoulder for a quick session on the whiteboard are long gone, and unless everyone has costly and compatible technology at home, it is going to be incredibly hard to emulate. I have a Surface Pro with a pen at hand for ad-hoc drawings I can do over Teams or Slack, but not everyone has one at home, unfortunately.

I am usually spending my time describing how components or systems interact with each other. For that, I generally draw a bunch of boxes and lines on a whiteboard to show the sequence of interaction which is great for getting some knowledge out of my head, and hear others input and collaborate at the whiteboard.

Now my phone is full of a mixture of whiteboarding sessions and baby photos. We need to get this information out digitally so we can easily share and collaborate remotely and asynchronously.

Enter PlantUML

Have you ever tried to use a visual editor to draw a sequence diagram? It’s hard enough getting things to line up, and good luck trying to change the sequence in any meaningful way!

PlantUML is a way to describe many UML style diagrams using text, which is great for developers as we love to stick things in source control to track changes and collaborate.

The basic syntax for a line in a sequence diagram shows that one participant is sending a message to another participant, using activity lines:

Sequence Diagram

@startuml
participant User

User -> A: DoWork
activate A

A -> B: << createRequest >>
activate B

B -> C: DoWork
activate C
C --> B: WorkDone
destroy C

B --> A: RequestCreated
deactivate B

A -> User: Done
deactivate A

@enduml

There are plugins for your favourite editors (Jetbrains, VSCode etc.) so you can see your documents come to life in real-time. I have been able to share my screen and write up a quick sequence diagram over a video call with my teammates and have that real-time collaboration that I do miss from being in the office. You can install plugins for Confluence and have living documentation in there if that is your preferred medium.

If the diagram is about an existing project, I like to throw it into the codebase so it is easy to reference. Personally I prefer to have my documentation within git to be versioned along with code, instead of a confluence page that can quickly become outdated.

The use of PlantUML and Markdown for living documentation within your git repo is a game changer.

They do say a picture is worth 1000 words, and in the case of software architecture, I couldn’t agree more.

Other formats

Day to day I find the sequence diagram the most useful, however, Plant can handle a range of UML documents including:

Class Diagram:

The class diagram

@startuml

abstract class AbstractList
abstract AbstractCollection
interface List
interface Collection

List <|-- AbstractList
Collection <|-- AbstractCollection

Collection <|- List
AbstractCollection <|- AbstractList
AbstractList <|-- ArrayList

class ArrayList {
  Object[] elementData
  size()
}

enum TimeUnit {
  DAYS
  HOURS
  MINUTES
}

annotation SuppressWarnings

@enduml

Activity Diagram:

The activity diagram

@startuml

start
:ClickServlet.handleRequest();
:new page;
if (Page.onSecurityCheck) then (true)
  :Page.onInit();
  if (isForward?) then (no)
    :Process controls;
    if (continue processing?) then (no)
      stop
    endif

    if (isPost?) then (yes)
      :Page.onPost();
    else (no)
      :Page.onGet();
    endif
    :Page.onRender();
  endif
else (false)
endif

if (do redirect?) then (yes)
  :redirect process;
else
  if (do forward?) then (yes)
    :Forward request;
  else (no)
    :Render page template;
  endif
endif

stop

@enduml

And many others

Is it 100% natural and as easy as whiteboarding? Absolutely not! But it is a significant step forward to help us collaborate more effectively.