Diagram Proposal: Team Topologies

[Incognito]

Proposal

Introduce a diagram type named "Team Topology" which follows the conventions from https://teamtopologies.com/ .

The syntax must be able to:

1. Identify a team name (optionally)
2. Identify one of four a team types
3. Identify which of the 3 interaction modes connects to two teams (and in the case of XaaS, what direction).
4. Identify groups of teams (if there are any) which behave like teams themselves and can have interactions.

By default: Add a "Flow of change" arrow to the top or bottom of the diagram.

Here are the core components of the diagram

Stream#Stream
"Complicated Subsystem"#Complicated
"Enabling Team"#Enabling
"Platform Team"#Platform

I had a short discussion in Slack with one of the co-creators of TT and he suggested the layout engine could decide on the ideal layout, which might mean we do not need to offer positioning to the user (unless there are some technical issues).

Use Cases

Team Topologies is a way to diagram teams and how they interact. It is growing rapidly in popularity for software teams but also non-software companies use it.

Companies use it to discuss org structure and modelling to help teams reach "Fast Flow" of change.

Screenshots

Here are several examples I've taken off of google image search:

"Stream A"#Stream
"Stream B"#Stream
"Stream C"#Stream
"Stream D"#Stream
"Platform A"("Stream D")
"Complicated Subsystem team"#Complicated
"Enabling Team A"#Enabling
"Enabling Team A"--Facilitation->"Stream A"
"Complicated Subsystem team"--Collaboration-->"Stream A"
"Complicated Subsystem team"--XaaS-->"Stream B"
"Stream D"--XaaS->"Stream C"
"Stream D"--XaaS->"Stream B"
"Stream D"--XaaS->"Complicated Subsystem team"
"Stream D"--Collaboration-->"Stream C"

[wip]

[wip]

[wip]

Syntax

f1#Stream
f2#Stream
f1--XaaS->f23

How to expose "groups" is still work-in-progress and possibly ship as a 2nd iteration on this feature. Presently under consideration is:

PlatformGroupName(teamName1, TeamName2, ... ), or with quoting for whitespace too: "Platform Group Name"(teamName1, TeamName2, ... ).

Implementation

I will try and implement it myself.

[Incognito]

Request for early feedback on the grammar/JISON file:

#4678 (review)

[sidharthv96]

Some notes on the grammar for discussion

1. Should we use the existing mermaid convention for defining the type of team? We could use the brackets for differentiating type of team. The rendering can be tweaked to fit the required standards.

flowchart
   T1(Stream)
    T2{{Complicated subsystem}}

Loading

flowchart
   T1(Stream)
    T2{{Complicated subsystem}}

2. Unicode (mandatory) & markdown (optional) support in names. id("Text with unicode)
3. How do we express an interaction method that spans multiple teams?

Grouping can ship as a 2nd iteration, but we need to have a plan on how the grammar should work so that we don't have to modify any existing grammar.

---

When writing a complex diagram, useage of symbols can help reduce the effort.

teamTopology
t1#Stream
t2#ComplicatedSubsystem
t3#Enabling
t4#Stream
t5#ComplicatedSubsystem
t6#Enabling
...

vs

teamTopology
t1("My team Name") <Need to express connection somehow> t2{"Complicated Y"}
t3["Enabler team 1"]
tx[["Awesome Platform?"]]

---

Can you write the code for the diagrams shown in the issue using the expected grammar (after we finalize)?

[Incognito]

@sidharthv96 Thanks for the feedback.

I'm unsure about your design goals with point 1. In TT we are limited to only 4 team types and each one has a different way to be drawn. What is the benefit of adding bracket types into the mix? From my POV it would reduce usability by making users have to remember what kind of brackets match with what kind of team type they want to use.

Point 2: Unicode makes sense. Markdown sounds tricky, do you mean for things like bold/italics or also images, links, tables, etc?

Point 3: Based on some short feedback from Matthew Skelton the preferred strategy is to leave the aggregation of things to the layout engine and explicitly identify each individual relationship as text (see point 2)

Grouping: My early idea was to write it like this: PlatformGroupName(teamName1, TeamName2, ... ), we can possibly quote the group name too: "Platform Group Name"(teamName1, TeamName2, ... ).

Code for the diagrams in the examples above: That's a great idea, I'll push that along as I work on this more.

[sidharthv96]

What is the benefit of adding bracket types into the mix?

1. It makes the grammar similar to other mermaid diagrams. Diagrams are easier to write.
2. <id><openingBracket><labelText><closingBracket> => t1("My Team Name"), t2["Another team"] format provides a natural way for labels to be placed with IDs.
3. In TT we are limited to only 4 team types, so a simple example in live editor could cover all the shapes with brackets and there's no need to remember 13 shapes like flowchart.

Unicode makes sense. Markdown sounds tricky, do you mean for things like bold/italics or also images, links, tables, etc?

Unicode and markdown are already supported by flowchart. "Quoting" should handle unicode, and you can skip markdown for now. You can refer to the flowchart implementation.

Point 3: Based on some short feedback from Matthew Skelton the preferred strategy is to leave the aggregation of things to the layout engine and explicitly identify each individual relationship as text

I agree that the layout should be left to the engine, your example code has cleared up my query.

---

Current syntax

"Stream A"#Stream
"Stream B"#Stream
"Stream C"#Stream
"Stream D"#Stream
"Platform A"("Stream D")
"Complicated Subsystem team"#Complicated
"Enabling Team A"#Enabling
"Complicated Subsystem team"--Collaboration-->"Stream A"
"Complicated Subsystem team"--XaaS-->"Stream B"
"Stream D"--XaaS->"Stream C"
"Stream D"--XaaS->"Stream B"
"Stream D"--XaaS->"Complicated Subsystem team"
"Stream D"--Collaboration-->"Stream C"

Proposed syntax

teamTopology
	ea[Enabling Team A] facilitation sa(Stream A)
	cs{"Complicated Subsystem team ♥"} collaboration sa
	cs xass sb(Stream B)
	sd("Stream D ♥") xass sc(Stream C)
	sd xass sb
	sd xass cs
	sd collaboration sc
	platform[["Platform A", sd]]

With support for multiple nodes in a connection.

teamTopology
	ea[Enabling Team A] facilitation sa(Stream A)
	cs{"Complicated Subsystem team ♥"} collaboration sa
	cs xass sb(Stream B)
	sd("Stream D ♥") xass sc(Stream C), sb, cs
	sd collaboration sc
	platform[["Platform A", sd]]

[Incognito]

I see the value in using symbols, and I like the ability to support multiple nodes in a connection. I also really like the multi-node concept. I think the next iteration of the grammar needs this.

I'm still hesitant about the concept of using bracket types to denote team type could reduce usability/simplicity. I've debated it with myself for the last hour however and I think it is probably fine to just use the brackets. I'm however wondering what the community would say when asked which grammar would be more usable to them. It would be a good opportunity to "fail early" with our assumptions.

Personally however, after sitting with your proposal for a while I don't feel like it is that hard to read.

[sidharthv96]

I suggested brackets as those are an existing convention in mermaid which simplifies the process of writing the diagrams.
I agree that there is a learning curve, but in this particular case, it's not very steep, and we can cover it in a single example. :)

[jgreywolf]

+1 for brackets to be consistent :)