Diagrams in Documentation

Diagrams in documentation, featuring diagrams.net. Virtual Meetup #6 of Continuous Documentation Regulars.

When authoring technical documents, we often struggle to find the easiest way to include diagrams. This article lists several diagramming tools and several ways you can use them to enhance the documentation for your users and to improve your authoring workflow.

Read on to find out more about the features and surprises diagrams.net and other tools had in store for us at this meeting of the Continuous Documentation Regulars.

Thoughts about diagrams

What makes us productive (or slows us down)

Asking this question about productivity in today’s meetup revealed a coder’s mind: We want diagrams stored in source code management and editable inside the IDE without switching contexts to another tool. We want co-workers to collaborate in creating a solution and to review our changes. Templates and examples help us to get started and to create consistent output.

Tools like Excalidraw allow for real-time collaboration, or allow sharing a JSON with other users. With diagrams.net we can store a ready-to-view diagram in source control that is editable at the same time.

The things that slow us down are inflexible data formats like Microsoft PowerPoint that are difficult to integrate: We don’t want conversions that are computation intensive or make our workflows slow and brittle. Fiddling with sizes of boxes, alignment and layout is time-consuming: We want to focus on the problem and its solution. The resulting diagram should be “good enough”. Tools like PlantUML auto-layout all elements all the time, but it’s a love-and-hate relationship: complex diagrams can make graphviz crash, and it might be impossible to get the layout “right”, especially when addressing people on the C-level. Users need to learn about idiosyncrasies that steepen the learning curve to get the results they want (or need).

When to use diagrams (and when not)

The first warm-up question was when to use diagrams and when not. The list of when the group used diagrams was long:

  • UML types for architectures (deployment, state, component, class, sequence diagrams; sometimes C4-style),
  • business processes and workflows (with flow charts or BPMN),
  • infrastructure (pipelines, deployment workflows and metrics), and
  • scribblings of any kind to make sense of existing code.

I observed that I don’t use diagrams for class diagrams. Why? Frauke found the right words for it: Never for “replacing stuff that could and should be checked in the code directly”. They tend to be outdated and out-of-sync too quickly.

Tools to use (and to avoid)

The second warm-up question asked what tools participants like and would use again, or tried and wish they hadn’t.

The tools that they didn’t want to use again were the office formats: Microsoft Powerpoint and Visio were mentioned multiple times. Tools like Rational Rose weren’t popular either. One participant used yuml.me in the past, but not anymore. Sparx Enterprise Architect received mixed results.

Lots of participants liked coder-friendly tools like PlantUml or ditaa. Draw.io/diagrams.net were popular as well, as well as plug-ins to Confluence like Lucidcharts and gliffy. Several fans of Excalidraw where in the meeting, also fans of ConceptBoard and Camunda’s Cawemo. Stand-alone tools like OmniGraffle, Signavio, TogetherJ, Camunda Modeller and Structurizr were also well-received.

Close-up on diagrams.net

The main focus of the meetup was diagrams.net, previously known as draw.io.

Reviewing the topics covered in the previous section, it scores a lot of points:

  • Editor that works in the browser and as a stand-alone application on Windows/​MacOS/​Linux/​Chrome OS.
  • WYSIWYG editor with lots of templates and example symbols.
  • IDE plugins, for example Visual Studio code and (soon) IntelliJ.
  • Store diagrams as editable PNG or SVG to use them in your documentation workflow without conversions.
  • Users can create libraries of re-usable shapes. See jgraph/drawio-libs for a list of available libraries (kudos to Ganesh and Frauke for sharing this).
diagram example styling
Figure 1. Example from diagrams.net

The shapes can be changed to hand-written style for lines and backgrounds. This matches with a handwriting-styled font like Kalam (kudos to Ganesh for sharing this practice). See Figure 1 for an example.

Ralf and I presented a short walk through how the editing workflow with the diagrams.net plugin for IntelliJ looks like:

  1. Start writing some AsciiDoc text using the AsciiDoc plugin for IntelliJ.
  2. Reference a non-existing image in the document like myimage.drawio.svg
  3. Use the shortcut Ctrl+Enter to create the image and switch to the diagrams.net editor within the IDE.
  4. Once you save the diagram and switch back to the document, the image is visible in the document’s preview.

This is the integration we love to see; hopefully there will be a pre-release of the diagrams.net IntelliJ plugin, soon. For now, you must build the pre-release manually for yourself.

During the meetup we looked deeper, and some features we see above come with a trade-off:

  • When choosing an editable PNG format, the result is a blob. You can’t show a diff on a blob. Therefore, it is not possible to review changes using standard code-review tools. It is also not possible to merge two changes to the same diagram from different branches, or to trace back an element to its original author.
  • The same is true for the editable SVG: It is a vector format and based on XML. But the changes are not human readable or mergeable. While the SVG part is XML, the editable content is base64 encoded: No chance to merge or review these changes.
  • Depending on the tools, a visual diff might be possible not at the code level, but on the visual level. Frauke shared a link to GitHub Blog on SVG viewing and diffing how a UI could look like. Other tools like Imagemagick have a visual diff that highlights the changes.

Embedding SVGs from diagrams.net in PDFs

After the meetup, Michael performed an experiment to embed an SVG created with diagrams.net in a PDF created by Asciidoctor PDF. As SVGs are vector based, they promise the best results in PDFs for printing compared to raster images like PNG.

While the SVG looked nice in the editor and the browser, it didn’t show up in the PDF as expected: The text was no longer word-wrapped, and an error message “Viewer does not support full SVG 1.1” appeared. Looking into the source code of the SVG we saw that diagrams.net embedded HTML inside the SVG. Embedding HTML is part of the SVG standard, and offers advanced formatting options like word-wrap, but only works in browsers. Asciidoctor PDF uses prawn-svg that doesn’t handle HTML embedded in SVG.

The diagrams.net FAQ shows how to uncheck two text formatting options; after that change, the PDF rendered nicely. According to the FAQ this also resolves problems of importing the images to vector based editors like Adobe Illustrator.

As an alternative, there is the tool Asciidoctor Web PDF (currently in alpha). It uses a Chrome based browser to render the PDF, and this can render the embedded HTML without issues. Using this tool, no change to the SVG was necessary, and the PDF with the image turned out as expected.

So here there are the idiosyncrasies we fear. This is something to watch out when working with the tool, and something to teach new users to avoid.

Will I use diagrams.net?

Looking at diagrams.net, there is a lot I like.

Things that I couldn’t achieve with PlantUML before:

  • Non-technical people can draw diagrams. This was always a pain with PlantUML.
  • The diagrams look nice and C-level friendly. With PlantUML, they weren’t always happy about the style and the auto-layout.

It’s on-par with PlantUML in other aspects:

  • Storing (reasonably small) diagrams in the version control system together with the code.
  • Diagrams work nicely in browser documentation workflows.
  • If (and only if) you know how (as described above) they also work in PDFs.

The one trade-off I see:

  • Diagrams.net is not diagrams-as-code, as they store a small, yet binary file in my Git repository.
    This will not work well with code reviews and merges.

So this will be a case-by-case decision for me. The more technical a project or diagram is, the more likely it will be for me to use PlantUML. For less technical projects and diagrams I’ll use diagrams.net.

Get in contact to share your feedback or tell others by sharing the link! If you enjoyed reading this article, consider joining the Continuous Documentation Regulars Meetup for one of the upcoming events.

Further reading

This section summarizes the tools together with their links (in no particular order):

Evergreen in diagrams-as-code. Supports lots of UML diagrams, and also Gantt diagrams. You’ll love it as long as you are fine with its auto-arranging of elements in the diagrams you create. Join their Patreon campaign and for just one USD a month you can enjoy their website ad-free!
Kroki provides a unified API with support for Mermaid, PlantUML and many more. No need to install local tools for diagrams any more! There are multiple ways to integrate it:
  • On-the-fly rendering in the preview (supported for example by the AsciiDoc plugin for IntelliJ).
  • Build time rendering (supported for example for Antora via the asciidoctor-kroki plugin).
  • On-demand rendering when viewing the HTML documentation in the browser.
Use the browser, or a stand-alone application on Windows, Linux or MacOS, or even integrated in your IDE. The SVG and PNG diagrams you save are viewable in standard viewers like a browser, and fully editable by their tool. This solves a lot of hassle. See section “Embedding SVGs from diagrams.net in PDFs” to pick the right options in the editor or the right tools for your tool chain if you want to use them in PDFs or tools like Adobe Illustrator.
Visual Studio Code plugin for diagrams.net
A plugin for this popular IDE for diagrams.net. Allows real-time collaboration using liveshare.
IntelliJ plugin for diagrams.net
A soon-to-be-released plugin for this popular IDE.
Update 24.12.2020: It’s alive! You can now download the plugin from the JetBrains marketplace.
yEd Graph Editor
Editor for graphs like flow charts and UML Class diagrams, but also BPMN. Works stand-alone or web-based.
Mingrammer Diagrams
Use Python code to describe your diagrams. Comes with a variety of stencils to describe your cloud infrastructure.
Use a pure diagrams-as-code DSL to create diagrams for sequence, class, state, pie and Gantt diagrams. Have a look at the live editor to try it. Install it via Node package manager. Uses Chromium in the background to render the diagrams in build chains or directly in the browser.
A collection of tools to extract IT architecture diagrams from code or to design systems. Based on the C4 architecture model.
Extension for PlantUML to draw C4 diagrams using the PlantUML syntax.
Online and Open Source tool to draw diagrams in the browser. Diagrams have a hand-written style. Use it online, collaborate in real-time. Users can use the public instance or host their own private instance.
Online visualization and collaboration, different kinds of diagrams.
Camunda BPMN, DMN and CMMN
Online tools and embeddable browser components to visualize and edit everything you need for processes, decisions and case management: BPMN, DMN and CMMN diagrams.
Camunda Cawemo
Online collaboration tool for workflows based on BPMN. Integrates with other components of the Camunda workflow suite.

(Looking for the summary? Go back to section “Will I use diagrams.net?” and find it there!)

Back to overview...