Diagrams in Documentation

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).

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):

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