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!
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.
Rolfe Dlugy-Hegwer 