Diagrams-as-Code with AI

Create diagrams alongside your code that are useable with LLMs

More and more teams are starting to use coding to tackle their diagramming and documentation challenges. Using plain text notations to create diagrams turns a traditionally artistic process into a systematic and data-driven approach. Using diagrams-as-code and models instead of traditional diagrams gives you many benefits, including storing your diagrams alongside your code, automatic consistency, and the ability to engage AI in the process.

Join this workshop to explore the more popular diagrams-as-code notations so that you can create diagrams-as-code as well as understand the diagrams-as-code that an LLM might generate for you. We all know that the output of an LLM cannot be trusted, so you need to understand the code the LLM supplies to you.

We will cover PlantUML, Mermaid, and Structurizr, for use alongside your code and in documentation and build pipelines. We will also delve into the use cases and limitations of using these diagrams-as-code with AI. All the tools we use in this workshop will be free to use.

Agenda

  • Introduction
  • Diagrams-as-code notations
    • Comparing PlantUML, Mermaid, & Structurizr
    • Diagrams vs. diagrams-as-code vs. models
  • PlantUML
    • Diagrams, syntax, and tools
    • Using PlantUML with LLMs
    • Exercises
  • Mermaid
    • Diagrams, syntax, and tools
    • Using Mermaid with LLMs
    • Exercises
    • Comparing PlantUML & Mermaid
  • Structurizr
    • Diagrams, syntax, and tools
    • Using Structurizr with LLMs
    • Exercises
    • Comparing PlantUML, Mermaid, & Structurizr
  • Wrap Up

Audience

Developers, Architects, Tech Leads, Technical Writers, Business Analysts, anyone wanting to adopt diagrams-as-code.

Learning Outcomes

  • Gain a grounding in PlantUML, Mermaid, and Structurizr
  • Understand the tradeoffs of diagrams-as-code and models vs. standard diagrams
  • Recognise the limitations and useful use cases of using diagrams-as-code with LLMs
  • Learn through hands-on exercises and interactive activities

FAQ

Q: Do I need to be a programmer to attend your workshop?
A: No. Some experience of coding or scripting will help, but the syntax of all three notations we will look at is fairly easy to learn for someone who has never coded, and we will use online tools with no setup required.

Q: What is the schedule for the workshop?
A: The workshop will be run in 2x 3.5 hour sessions on separate days. We will have breaks within these sessions.

Q: Will there be any homework?
A: You will be encouraged to apply your learning in the time between the taught sessions, but it is not mandatory. We will have time in the 2nd session to discuss anything you have done between the sessions.

Q: Will I receive the slides and teaching materials used during the course?
A: Yes, all materials will be made available to you, and you will be able to continue to access the GitHub repository we use in the workshop.

Q: Do you cover diagrams created with tools such as Draw.io or Visio?
A: Not in this course, but Jacqui runs other courses on Design Patterns for Software Diagrams. Please reach out if you are interested via https://jacquiread.com.

Q: Do I need to install anything before the workshop?
A: No, but you may want to optionally sign up for a free account with ChatGPT or another online LLM. All the tools we use will be online and free. Optionally you can use tools such as Structurizr Lite, Structurizr Cloud, or an IDE such as Visual Studio Code with plugins for the notations we will use. I will not be providing support for these or time to set these up in the workshop as the online tools are all that is needed.

All the tools we use in this workshop will be free to use. You will require a laptop, text editor, internet connection, and access to the following websites:

This workshop is available in full-day or two-day formats, which can be broken down into multiple half or full-days over a period of time.