Using UML and GraphViz diagrams to document business processes

[#1]

Recently I showed a technical program manager a UML timing diagram I made while learning to create them. It compared the timing of Agile sprints, feature development, software releases, and development milestones. “I have some serious cognitive dissonance going on here,” he laughed. “I’ve used timing diagrams, but I’ve never seen them used to capture business processes before.”

Our different perspectives got me thinking. As a non-developer, I don’t use UML diagrams to document code. I had to find other, real-life applications to practice my diagramming skills. The sequential nature of certain business processes seemed to be a good fit, so that’s where I started. It turns out that using UML diagrams in this way has some benefits and advantages, explained below. The examples are real but simplified and “anonymized.”

Note: To replicate these diagrams, you may need to adjust the syntax slightly depending on your versions of Confluence, GraphViz.exe, and macros mentioned below.

Directed graph: Jira workflow

This was an early effort to visually depict the change in status of Jira issues as work progressed. I used Bob Swift’s Digraph macro to create it. Each node contained a link to a corresponding wiki page with more details. The left-to-right orientation fits well with the page layout.

{
rankdir=LR;
rank=same;
node [shape=box,fillcolor=white,style="rounded,filled,dashed",color=brown,fontcolor=black]; Before;
node [shape=box,style="rounded,filled,solid"]
Before -> State1 -> State2 -> State3;
State1 -> State3 [label="Skip"];
State3 -> State4 -> State5 -> State6;
}

Sequence diagram: Roles and relationships

PowerPoint can be useful as a thinking tool but sometimes results in messy slides with many arrows as people think things through. This sequence diagram shows the same information exchanges as the slide but is much tidier.

One advantage of diagrams is that they can be edited in-page instead of having to edit a PowerPoint presentation, export slides as static images and then insert them into a wiki page.

@startuml
hide footbox
box "Team1" #linen
actor Role1
end box

box "Team2" #linen
actor Role2
actor Role3
end box

box "Team3" #linen
actor Role4
end box

Role4 -> Role1 : Sends this info
Role4 -> Role2 : Sends more info
Role2 -> Role4 : Sends info back
Role1 -> Role2 : Helps with this
Role2 -> Role1 : Helps with that
Role1 -> Role3 : Sends different info
Role3 -> Role1 : Sends different info back

@enduml

Activity diagram: Onboarding process

A team’s onboarding process needed review. The manager was surprised when I fired up Visual Studio Code during our discussion but the rigor enforced by a UML diagram had immediate benefits. Using an activity diagram with swimlanes required us to a) put the steps in sequential order and b) clarify who did what. It’s now more obvious that account creation happens before access is granted, which had been confusing before. In the actual diagram each step has a link to the instructions for doing it.

Everyone who sees this diagram “gets it” immediately and having a clear path to follow has made onboarding much smoother.

@startuml
|Manager|
start
:Tells new person to create accounts
then enter support ticket;
|New Hire|
:Creates accounts
----
* Account1
* Account2
----
Enters support ticket;
|Support|
:Grants access
----
* Tool1
* Tool2
* Tool3
----
Send welcome email;
|New Hire|
:Sets up tools;
:Gets to work;
stop
@enduml

Activity diagram: Qualification process

As I got better at diagramming I could tackle more complex processes. This one was an important and complicated process involving no fewer than five roles and several rounds of testing. If tests failed at any point in the process, it was “back to square one.” To insiders, this process was second nature and based on personal relationships. To outsiders it was understandably confusing. Now they are better equipped to contact people depending on where things are at.

In the actual diagram, the green ovals are linked to anchors on the Confluence page with more details about each step, but here they are linked to Google so you can see the syntax. Some of the steps are notifications, not actions, which helps ensure that the appropriate people are notified at certain points.

@startuml
|Role1|
start
#lightgreen:[[http://www.google.com A]];
:Request;
|Role2|
repeat
repeat
#lightgreen:[[http://www.google.com B]];
:Generate and
upload;
|Role3|
#lightgreen:[[http://www.google.com C]];
:Initiates;
|Role4|
#lightgreen:[[http://www.google.com D]];
:Tests;
repeat while (Test passes?) is (No)
-> Yes;
|Role3|
#lightgreen:F;
:Approves,
requests;
|Role4|
#lightgreen:I;
:Tests again;
repeat while (Tests pass?) is (No)
-> Yes;
|Role3|
:Notifies;
|Role5|
#lightgreen:J;
:Releases;
|Role2|
#lightgreen:K;
:Documents;
:Archives;
stop
@enduml

Timing diagram: Scrum and milestones

I needed a real-life example to practice a timing diagram so I tried to capture a typical rhythm of releases, milestones and Agile sprints and story points. Time is a scale that remains constant, so a timing diagram can keep cycles “in sync” or “in proportion” with each other, which is something that can easily get distorted in PowerPoint. I didn’t use this diagram anywhere but it was a good exercise.

@startuml
concise "Program Phase" as Phase
concise "Feature Groups" as Features
concise "Releases" as Version
concise "Cycle" as Cycle
concise "Scrum" as Scrum
robust "Velocity" as Points
Points has 18,16,14,12,10,8,6,4,2,1,0
scale 7 as 35 pixels
@-2
@0
Scrum is "Sprint 1"
Phase is "Phase 1"
Features is "Feature Group"
Cycle is "Cycle 1"
Points is 12
Scrum -> Points : Meeting
Version is "V.1"
@2
Points is 10
@4
Points is 8
@6
Points is 6
@8
Points is 4
@10
Points is 2
@12
Points is 1
@13
Points is 0
@14
Scrum is "Sprint 2"
Scrum -> Points : Meeting
@28
Scrum is "Sprint 3"
Cycle is "Cycle 2"
Cycle -> Points : Meeting
@42
Scrum is "Sprint 4"
Points is 0
Scrum -> Points : Meeting
@56
Scrum is "Sprint 5"
Cycle is "Cycle 3"
Version is "V.2"
@70
Scrum is "Sprint 6"
@84
Scrum is "Sprint 7"
Cycle -> Features : XYZ
Features is "Feature Group"
Cycle is "Cycle 4"
@98
Scrum -> Phase : ABC
Phase is "Phase 2"
Scrum is "Sprint 8"
@112
Features is "Feature Group"
Cycle is "Cycle 5"
Version is "V.3"
@120
Phase is "Phase 3"
@enduml

To sum up, benefits of using diagrams to document business processes include,

• Can be edited directly in the Confluence page by multiple contributors

• Fewer formatting options leads to fewer distractions, more uniformity and ease of reading

• Encourages rigor in thinking sequentially or across roles

• Helps identify gaps and assumptions

• Visuals encourage speedy comprehension of even complex processes.

I am currently helping some managers who have used sequence diagrams to map out work. Each step in the diagram will be linked to individual Confluence wiki pages with more detail. Getting familiar with UML diagrams, even as a non-developer, made me better prepared to support their documentation effort.

For more information, start at https://www.graphviz.org/ or https://plantuml.com/ . There are many tutorials, tools, examples and use cases on the Internet to get going. It’s fun and worth doing!