Everett Toews

Helping you shave narwhals

Diagramming is a Solved Problem

12 Jan 2022

There are numerous diagramming tools in the market and they all do a very good job of diagramming. However, almost all of them suffer from a fundamental problem that makes the diagrams they produce much less valuable. They make it impossible to share a rendered version of the diagram (e.g. png or jpg) that is conveniently editable. drawio.com has solved that problem brilliantly.

In software development and architecture, diagrams are enormously valuable as they can communicate an amazing amount of information at a glance. Nothing gets everyone on the same page like a good diagram. Like any documentation, diagrams can rapidly go out of date so it is absolutely essential that diagrams are conveniently editable.

Most of the time, diagrams are embedded in other documentation, whether it’s a wiki, website, markdown, or something else. The version that is embedded is a rendered version of the diagram (e.g. png or jpg) so it can be displayed in any browser. Rarely is the editable version included alongside the rendered version. The editable version has to be hunted down as it is typically stored elsewhere. You’re lucky if you can find it, find a version of the diagramming tool to edit it, and acquire a license to even open the diagramming tool at all. With so many barriers, it’s often impossible to update a diagram and most of its value is lost.

drawio.com has solved that problem by embedding the editable version of a diagram within the rendered version and making it convenient and free to edit it in app.diagrams.net (you can find the docs at drawio.com/doc/).

Edit a Diagram

Imagine you’ve come across the diagram below in some documentation. Note that it’s a png file being displayed in your browser. You can edit it right now using the instructions below.

Scaling Communication
Scaling Communication
Save this diagram and open it in app.diagrams.net to edit

Instructions

  1. Right-click on the diagram and choose “Save Image As…” (or equivalent in your browser)
  2. Open app.diagrams.net
  3. You’ll be greeted with a dialog to “Save diagrams to:”, choose Device
  4. Choose Open Existing Diagram
  5. Choose the diagram you just saved

You can now edit the diagram to your heart’s content.

Save an Editable Diagram

If your browser is capable and you’ve allowed it, app.diagrams.net will actually automatically save that diagram directly to your hard drive as you update it.

If you’ve created a diagram from scratch, you should know how to explicitly export a rendered version with the editable version embedded.

Instructions

  1. Open app.diagrams.net
  2. You’ll be greeted with a dialog to “Save diagrams to:”, choose Decide later
  3. Edit the diagram to your heart’s content
  4. You can save an editable version two ways:
    1. File > Save as …
      1. In the dropdown to the right of the filename, choose “Editable Bitmap Image (.png)”
      2. Click Download
    2. File > Export as > PNG …
      1. Fill in the properties however you like
      2. Check “Include a copy of my diagram”
      3. Click Export

You now have a diagram that can be displayed anywhere and easily edited.

Share an Editable Diagram

Because your diagram is already a rendered image, it is trivial to share. Just embed or send the image wherever you need to.

However, your diagram is already a rendered image, it is not obvious that it’s also editable!

When sharing the diagram, be sure to include some indication that the diagram is editable (e.g. a caption).

For example, in a website like the diagram above you can use an img title attribute and/or a caption.

<figure>
  <img class="img-centre"
       title="Save this diagram and open it in app.diagrams.net to edit"
       alt="Scaling Communication"
       src="/img/posts/scaling-communication.drawio.png"/>
  <figcaption style="text-align: center;">
    Scaling Communication
    <br/>
    <sub>
      Save this diagram and open it in app.diagrams.net to edit
    </sub>
  </figcaption>
</figure>

Deploy app.diagrams.net

“But what if app.diagrams.net goes down for any reason? Maybe permanently! I won’t be able to edit my diagrams!” I hear you say. It’s true that could be a problem but it’s definitely solvable.

The simplest solution for most people is to just download the Desktop version, save it somewhere, install it, and use that.

Another option is to deploy the app.diagrams.net web application yourself. It’s relatively easy if you already have a GitHub account.

Instructions

  1. Go to github.com/jgraph/drawio
  2. Click Fork (in the upper right corner)
  3. In your forked repo, click Settings
  4. Click Pages
  5. In the Source section, choose Branch: dev
  6. Click Save

A message will appear saying something like “Your site is published at https://etoews.github.io/drawio/”.

However, if you click the link, you’ll only see the README.md from the repo. You need to append src/main/webapp/ to the URL in your browser.

The full URL will be something like https://etoews.github.io/drawio/src/main/webapp/. An easily hosted version of app.diagrams.net!

Integrations

JGraph, the company behind app.diagrams.net, provides an amazing base feature set for free. They also offers many paid integrations to make using it easier for businesses. I wholeheartedly support this. If you belong to an organisation, I recommend looking these integrations to see if one fits your use case.

Coda

In my opinion, app.diagrams.net solves a long-standing and fundamental problem with diagramming. You’re able to embed an editable version of a diagram within the rendered version and it’s convenient and free to edit. Now there won’t be any excuses from keeping all diagram up to date!