Rant: We need more diagrams, not more diagramming tools

Words aren't always enough. I was trying to digest the Keycloak documentation on securing applications and after spending eight hours on that page, I finally realized that I was trying to construct diagrams in my head using the words. I was trying to construct the control flow in my head using the words on that page. And that is almost always a lossy transmission of information. I believe that a few sequence diagrams (uml, mermaid) can do wonders in that documentation, helping both people who need words and those who need images. And the verbal people can communicate with the visual people using the images and the text!

There's a dearth of diagrams in software project documentation. You could respond by telling me that most software projects don't even have documentation so expecting diagrams is a stretch. To that, I say that accepting diagrams as documentation might help address the issue. Contributors might not implicitly know that diagrams are acceptable contributions so explicitly mentioning it and maybe even documenting what diagrams could be useful to the project might improve the documentation overall.

At an internal coffee hangout yesterday, I commented on the fact that SaaS tools have slowly crept into our development process, one at a time. One such tool is LucidChart. If you use LucidChart, I would like you to ask yourselves a simple question - the last time you used LucidChart, did you collaboratively work on a diagram with your team? Or did one person on the team create the diagram and the rest reviewed it or discussed it? Don't get me wrong. I'm not advocating that everyone ditch LucidChart. But now that GitHub can render diagrams in Markdown files using mermaid.js, does it still make sense for your team to continue using LucidChart?

Taking a step back, you can imagine two main reasons a team might choose to use diagrams

• They are trying to model the system that is being built and diagrams are a useful way to explain the system to the rest of the team. This diagrams are usually built to be thrown away.
• They are documenting the software system and its architecture. These diagrams are meant to stay. The team might have decided that it is worth polishing a temporary diagram created earlier and maintaining it as part of the application documentation.

Going back to LucidChart, are you creating temporary diagrams that are meant to be thrown away? Or are you creating permanent diagrams that are meant to be maintained and should stay up-to-date? If they are temporary and don't need collaboration, are you sure you need a tool like LucidChart? If they are meant to be permanent, did you consider the mental overhead of maintaining a document that lives outside of the source code repository e.g. GitHub?

In the end, I believe that we need more diagrams in the software world. The discourse around whether the diagrams should be temporary or permanent can happen after they actually exist. We need more software developers creating diagrams and we need them to create more diagrams. Only after people become comfortable with diagramming can they meaningfully judge whether a diagram should stay or if it can be thrown out. We need to become comfortable asking each other the scope of diagrams we are creating. Only then can we evaluate the best tools for the job and the cost of introducing new tools into the existing developer workflow.

Epilogue: I am disappointed in myself. This post started as a rant. A part of me was simply trying to vent but another part took over that impluse and tried to derive potentially meaningful advice/takeaways/conclusions.