Work Systems Topology using PlantUML (Part 1)

Author

Thomas Krause

Published at

September 1, 2024 6:05 PM (GMT+2)

Tags

flightlevelsvisualizations

Summary

In this post, I explore Work Systems Topology using PlantUML.

Motivation

The first of the 5 Flight Levels System Design activities is to visualize the current state. While I’m aware that the gold standard for this purpose is Miro, I’m always searching for better/new/different ways to achieve things in order to see new opportunities.

That brought me to my old friend PlantUML, which is a textual diagramming tool (aka diagrams as code). While it is primarily used for slightly different purposes, it should be general enough to also do Flight Levels related visualizations with it. Reasons to do so could be (without order and without any ambition to be complete):

• The beauty that comes with using pure text as a medium
• Search & Replace works like a breeze
• In a smart editor you can get PlantUML syntax support and smart content suggestion support by copilot in parallel
• Works well with version control systems, gives history, diff etc.
• Machines (aka AI) reads and speaks text easier and more accurate than graphics.
• Decouple content and style
• Focus on the actual information, no need to fiddle around with fonts, colors, aligning shapes etc.
• Style consistency built-in
• Style customizability built-in
• Some aspects we want to try here that go beyond diagrams only, based on composability and exchangeability:
• decentralize the maintenance of diagrams
• bigger work systems can be visualized putting aggregated sub-systems together
• zoom out to a systems of systems view without duplicating work
• what-if analysis with multiple options
• previous/current state and current/future state analysis
• mix and match different diagram types
• Meet your people where they are: If you’re working with nerds, use nerd tools 😀.

Let’s go

Step 1 - Showing the basic graph

Let’s start with a small work system topology. We have all three flight levels involved, 2 products are part of it, 4 teams altogether.

We’re using PlantUML component diagrams for our purposes. All we need is boxes and arrows, this is what these diagrams provide. The syntax is pretty easy:

@startuml FLD04 #1

title Work Systems Topology using PlantUML

[The Innovators] -up->> [Product 1] : contributes
[The Innovators] -up->> [Strategy] : contributes
[Team 1] -up->> [Product 1] : contributes
[Team 2] -up->> [Product 1] : contributes
[Team 2] -up->> [Product 2] : contributes
[Support & Services] -up->> [XFunctional] : contributes
[Product 1] --up->> [Strategy] : contributes
[Product 2] --up->> [Strategy] : contributes

@enduml

This is what we got. A bit gray, still a bit unlevelled, but it shows the general idea. However, at least the part with Support & Services and XFunctional is placed a bit off.

Step 2 - Add some Levelling

Component diagrams do also provide some grouping mechanisms, Package is one of it - good enough for what we have in mind. Let’s bring our work system contributors to the correct Flight Level.

In the first section we introduce the contributors and assign them to a package. In the second section we draw the connections between the contributors.

@startuml FLD04 #2

title Work Systems Topology using PlantUML

package FL3 {
  [Strategy]
}

package FL2 {
  [Product 1]
  [Product 2]
  [XFunctional]
}

package FL1 {
  [The Innovators]
  [Team 1]
  [Team 2]
  [Support & Services]
}

[The Innovators] -up->> [Product 1] : contributes
[The Innovators] -up->> [Strategy] : contributes
[Team 1] -up->> [Product 1] : contributes
[Team 2] -up->> [Product 1] : contributes
[Team 2] -up->> [Product 2] : contributes
[Support & Services] -up->> [XFunctional] : contributes
[Product 1] --up->> [Strategy] : contributes
[Product 2] --up->> [Strategy] : contributes

@enduml

That already looks more flightlevel-ish 😀. However, I think we can do a bit better.

Step 3 - Add some Flight Levels Glitter

Our aim is to separate content and style, so we put all the styles in a separate document. For doing the magic to apply the right styles to the right shapes we add a so called stereotype - <<FL1>> to the Flight Level 1 contributors - to the respective components. In the style document these stereotypes are defined in color, shape etc. Furthermore, the style document contains a legend to be inserted (and a small brand notice).

Step 4 - Add some Flight Levels specialties

The current notation of system topologies can have some more variations, namely:

1. Drawing a team that does not run its own FL1 system embedded into the respective FL2 system.
2. Connecting two FL2 systems in both directions.
3. Levelling the dependent FL2 systems within the FL2 area.

We can achieve this in the following manner:

1. This is about Team 1. It only contributes to Product 1, may not need its own FL2 system. Component is a container shape, we can just write:
Copy

  component "Product 1" <<FL2>> {
    [Team 1] <<FL1>>
  }

2. Well, easy enough we can draw arrows in both directions. If Product 1 and Product 2 need to interact with XFunctional (and vice versa) we use:
Copy

[Product 1] <<-up->> [XFunctional]
[Product 2] <<-up->> [XFunctional]

3. happens automatically, if we use the up notation.
4. If we want to focus a bit more on the FL2 systems, we can add th following to the diagram:
Copy

remove <<FL3>>

Step 5 - Include styles from Github

All good, to make it a bit more practical, I’ve added the initial style document to a public Github repository.

The include statement is now

!include https://raw.githubusercontent.com/worksystems-design/plantuml-flightlevels-lib/develop/defs/fl-wst.iuml

That gives you the chance to directly play with the diagram here. Have fun!

What’s next?

So far we touched the basics only. Let’s explore some real world scenarios with a Flight Levels topology (and more) in the next post.