Diagrams-as-code for Kubernetes.io

Mermaid is a Javascript-based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development.

https://github.com/mermaid-js/mermaid

In my recent interview with Tim Bannister, Tim encouraged contributors to create more diagrams for the Kubernetes docs based on the new diagram guide that chrismetz09 created in December 2021.

Notably, this guide shows how to code diagrams using mermaid.js in a live editor!

Mermaid lets you create diagrams and visualizations using text and code.

This notion of diagrams-as-code has tremendous appeal for me! To illustrate why, let me tell you a quick story.

A few years back, I enlisted the help of THE primary graphic designer where I worked to create an information-rich diagram for some product documentation. Because of her talent and organization’s size, she was very much in demand. Using specialized tools, she designed a beautiful and informative diagram and exported it to a graphics file, which I published. A few weeks after publication, the software engineering team made a software change, and just like that, the diagram became outdated!

That approach was much better than the ad-hoc approach that had preceded. At least now, our diagrams were expertly designed, correctly branded, and consistent across all our products.

Unfortunately, that new approach could not be scaled up to meet the customer demand for properly-illustrated documentation, which I estimate at a minimum of 5000 new or updated diagrams per year. I arrived at this figure by estimating ten-plus diagrams per product, times fifty-plus products, times ten-plus additions/updates per product per year. (10+ x 50+ x 10+ = 5000+)

With that backdrop, the benefits of having diagrams-as-code seem significant:

  • Unlimited contributors can create and maintain diagrams using free and open-source software.
  • Teams can store and manage the code for diagrams alongside the documentation source.
  • The tooling separates content from presentation to give all diagrams a consistent look and feel.

Moreover, having source code for diagrams makes it is easier to search for specific terms when updating diagrams and conducting peer reviews.

I think it would make sense to give this new approach a try.

Leave a Comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s