Welcome to The Hitchhiker’s Guide to PlantUML!

Where system diagrams meet system reality

Imagine

Tip

Press play

Imagine being able to

1. share a model or diagram between all members of the team that they can all understand and contribute to and edit

2. draw diagrams like below automatically from a text description.

3. describe a system before you build it, when you’re building it, and as you maintain it into the future - keeping the description and the system current, and in sync.

4. maintain that text version in a source code repository beside the code for the system it is describing

Imagine having a diagramming tool that

1. fits with a developer workflow, and developers are comfortable using

2. enables lightweight just-enough AgileModeling in a way that meets AgileModelingBP

3. fits with modern practices of Continuous Integration Continuous Delivery - and “everything as code” including diagrams.

Well that’s what PlantUML gives you, and more…

PlantUML Diagram Examples

Blah Blah Blah… play!

This guide walks through creating PlantUML diagrams, including the ones shown here.

Diagram of a Typical Network

This uses the Plantuml Stdlib Open Security Architecture icon set. See Create a Diagram of a Typical Network

Diagram of an AWS Architecture

This uses the AWSlib icon set. See Create Real Life AWS Diagrams

Diagram of a Kubernetes Architecture

This uses the Azure and Kubernetes icon sets. See kubernetes

Diagram of a Global Widget Production System Using C4

This uses the C4 Lightweight Software Architecture Description Method. See Using C4 To Architect ACME Global Widget Production

Introduction

• 1. About PlantUML
  • 1.1. Diagrams As Code
  • 1.2. Shared Lexicon of Understanding
  • 1.3. Interview with Arnaud Roques (creator of PlantUML)
  • 1.4. Useful PlantUML Links
• 2. About this Guide
  • 2.1. The Story
  • 2.2. Scope
  • 2.3. Goals
  • 2.4. Principles
  • 2.5. Credits
  • 2.6. Feedback
• 3. Sections of the Guide

Using Standard Library

• 1. Create a Diagram of a Typical Network
  • 1.1. Example Network Diagram
  • 1.2. Select an icon library
  • 1.3. View all the icons with listsprites
  • 1.4. Gather the icons we need
  • 1.5. Decorate the Icons
  • 1.6. Create the diagram by connecting things together
  • 1.7. Change the Layout to Vertical
  • 1.8. Change the Layout by grouping icons together
  • 1.9. Add a Legend Table and a Note
  • 1.10. Conclusion
• 2. Create Real Life AWS Diagrams
  • 2.1. AWSArchitectureBlogSample1
  • 2.2. AWSArchitectureBlogSample2
  • 2.3. AWSArchitectureBlogSample3
• 3. Kubernetes and Azure
  • 3.1. Original
  • 3.2. PlantUML Equivalent
• 4. Google Cloud Platform‎
  • 4.1. Original
  • 4.2. PlantUML Equivalent
  • 4.3. Find icons
  • 4.4. Gather the icons we need
  • 4.5. Connect The Icons
• 5. Using C4 To Architect ACME Global Widget Production
  • 5.1. C4 ACME Global Widget Production

PlantUML Features

• 1. Use Images in Diagrams
  • 1.1. Deployment Diagram Elements
  • 1.2. Standard Library Sprites
  • 1.3. Create A Sprite
  • 1.4. Images
• 2. Scaling Sprites
  • 2.1. Scaling Sprite Options
  • 2.2. Revisiting scalebigsmall-label
• 3. Procedures and Keyword Arguments
  • 3.1. Defines Are Deprecated
  • 3.2. Default Values
  • 3.3. Keyword Arguments
• 4. PassSpriteAsParameter
  • 4.1. Understand How To Pass A Sprite To A Procedure
  • 4.2. Understand How To Pass A Sprite To A Procedure - using unquoted keyword
  • 4.3. Use Procedure Defaults
  • 4.4. So What?
• 5. Colors
  • 5.1. Hex Codes and Pre-defined Colours
• 6. Layout
  • 6.1. Arrows for Layout
  • 6.2. up down left right
  • 6.3. left to right direction
  • 6.4. top to bottom direction
  • 6.5. hidden
  • 6.6. nodesep and ranksep
  • 6.7. together
  • 6.8. linetype polyline ortho
• 7. Tricked Out Diagrams (aka Diagram Annotation)
  • 7.1. Notes
  • 7.2. Handwritten
  • 7.3. Title
  • 7.4. Footer
  • 7.5. Comments
  • 7.6. Caption

Understanding Standard Library

• 1. PlantUML Stdlib Overview
  • 1.1. PlantUML Standard Library Overview
  • 1.2. Superset Of Parameters
• 2. PlantUML Stdlib Under The Hood
  • 2.1. Goal
  • 2.2. Steps to Understanding
• 3. PlantUML Stdlib Under The Hood 2
  • 3.1. Step-by-step Towards A Standard Macro
  • 3.2. Close But…
  • 3.3. Procedure Keyword Arguments
  • 3.4. Extensibility

Standardising Standard Library

• 1. Standard Library - What We Have And What We Want
  • 1.1. Observations on Standard Library
  • 1.2. Macro Definitions
  • 1.3. What a User Wants In A Standard Library
  • 1.4. User Stories
• 2. Standardising Standard Library
  • 2.1. Plantuml Stdlib Terminology
  • 2.2. Plantuml Stdlib File Layout
  • 2.3. Standardising Sprites
  • 2.4. Standardising Icon Macro API
  • 2.5. Mode Example
  • 2.6. Mode Demo

Future

• 1. Thoughts For The Future
  • 1.1. A Showcase Template Site
  • 1.2. Hyperlinked Interactive Diagrams
  • 1.3. Machine Processing Of Text Files
  • 1.4. Architecture Icon Sets
  • 1.5. Security Modeling
  • 1.6. Github Actions and Workflows
  • 1.7. Guide for PlantUML Diagrams
  • 1.8. Interactive Notebook Guide
• 2. To Do List

Annex Standard Library C4

• 1. C4 Lightweight Software Architecture Description Method
  • 1.1. Introduction
  • 1.2. CheatSheet
  • 1.3. Video Presentation
  • 1.4. Related Methods
• 2. Using PlantUML Stdlib C4 Lightweight Software Architecture Description Method
  • 2.1. C4
  • 2.2. C4 PlantUML
  • 2.3. C4 Example Big Bank

Annex

• 1. GitHub File Finder
• 2. Journey to Documentation as Code
  • 2.1. My View On Documentation From 2013