A UML and DOT / Graphviz diagram gallery for impatient beginners

[#1]

Learning how to make UML diagrams in Confluence was an uphill slog at first. A lifelong learn-by-doing disciple, I’d bent HTML, CSS and JavaScript to my will through sheer force of personality and lots of Googling and dark chocolate. But without any background in computer science, without having ever written code, UML diagrams started out as a very hard nut to crack indeed.

I was excited to learn how to turn text into images. I found online documentation and an old O’Reilly book on UML. Boy, did I crash that crash course. What I learned was…how much I needed to learn!

The kind of guide I wanted was very different from what I found. I was startled to find most resources “explained” diagrams without ever saying what they actually were; I was forever walking into the middle of some highly-advanced conversation. I needed context, explain-to-an-8-year-old-level answers to my silly rank beginner questions, and lots of simple examples that I could gleefully mash up into small successes. My use cases were very different too, business processes instead of components.

Little by little, in my spare time, I kept throwing UML at my brain until it started to stick and I could apply what I’d learned to actual, real-world documentation needs: a Jira workflow, an onboarding process, a qualification process.

As I learned and practiced, I took notes. I realized that even developers with deep coding experience might want to add diagrams but not know UML. They’d have questions too, and no time to learn an entire modeling language or install Visio. Two and a half years after I started, I wrote the guide I wish I’d had in the very beginning: “UML and DOT diagrams for impatient beginners.” (It’s in our Confluence wiki, of course, available to any internal user.)

What’s in the guide? Let’s take a look.

UML and DOT 101

There’s a short opening paragraph which explains the very basics of what UML and DOT are (languages), what Graphviz is (both a rendering engine and a Confluence macro) and which macros display which types of diagrams.

FAQs

There are a few FAQs that answer the questions I had: What is this, anyway? How do I know what kind of diagram to use? What Confluence macros should I use? How does this work? (I still haven’t found an accessible explanation of how Confluence, macros and Graphviz work together.) How could I work on diagrams without breaking a wiki page?

The diagram gallery

The bulk of the guide is a three-column image gallery with a simple example of each kind of diagram. I wanted a page where I could scan through visual examples with a use case in mind. (Other websites, such as the excellent https://real-world-plantuml.com/, present diagrams by category which presupposes you know what kind of diagram you need.) Each example contains the name of the diagram, a short description, the diagram itself, and a “see the code” block, plus links to related documentation.

The PlantUML macro section includes typical activity, state, component, class and sequence diagrams. It also includes examples for work breakdown structure, MindMap, ArchiMate and Gantt diagrams which will become available soon. DITAA, timing, AsciiMath, LaTeX and SALT diagrams are in this section too, plus XEarth and JCCKit examples.

In the DOT / Graphviz section, there are examples of directed and undirected diagrams in default DOT format, plus examples of twopi, neato, circo, patchwork, osage, fdp and sfdp layouts. There’s also demonstrations of the Graph from Table, Flowchart, Digraph and Graph macros.

How to

This section is still under construction, and will be a cheatsheet on how to do all the things I often do with diagrams, such as adding hyperlinks, changing colors, adding code comments, and using swimlanes. I’ll link to the PlantUML and Graphviz documentation as well as other resources.

Troubleshooting

There’s a short how-to section that explains some reasons why diagrams might not work as expected and what can be done about it. The guide is tailored to our particular Confluence instance, as I have learned that different versions of Confluence, macros, Graphviz rendering engine, and syntax can produce different results.

What’s working, what’s next

As I mentioned, I use the guide on a regular basis to look at examples while I ponder a use case. I use it to show users what is possible as they mull over their own use cases and possible services or Confluence add-ons. Learning about sequence diagrams has enabled me to help some architects and program managers who were sketching out work to be done. I’ve helped a few users improve their complicated diagrams. A couple regular Confluence contributors have learned more about activity diagrams so they can help me keep some business process pages up to date (and I love them for it).

Over time I’ll add links to more example pages and use cases, as I want to understand more about what information challenges our wiki users are trying to overcome. The guide will be continually improved to jump-start anyone who wants to add a diagram to Confluence without the steep learning curve.

If users in your organization use UML and DOT diagrams, especially for nontypical use cases, I am interested in learning about them!