As a computer science major in college, I learned about Unified Modeling Language (UML) as a way to visually document software. However, I soon found designing and maintaining those images to be more of a pain than they’re worth. I had to reshuffle images on graphics programs for every minor change, so keeping documentation up to date proved to be impossible.
Recently, however, I discovered that someone invented a language, called Mermaid, to convert a simple Markdown file into readable – even elegant – graphics. I had to check it out, so I read this short little book by Ashley Peacock. After completing it over two days, I’m even more excited than when I started to apply it to my work.
In this book, Peacock describes the main graphical formats that can be produced with Mermaid. He also describes the “4Cs” – context, container, components and code – where Mermaid can bring ideas to life better than mere words. He also describes different scenarios where Mermaid can help to document niches in software development.
Mermaid has an online editor, which I used to get started, but I plan to use it mostly via a command-line shell script, freely downloadable from GitHub. Also, I was excited to learn, at the end of this book, that Mermaid can be integrated into normal Markdown files and viewable as a part of GitHub READMEs. Adding easily configurable graphics might transform my expressiveness in documentation!
Overall, I’m super-excited to apply these concepts to my work. Other software developers and especially software designers should join me in this endeavor. Explaining software proposals to colleagues and managers can be one of the hardest tasks. As with most of science, a good graphic can seal the deal, and a lack of one can break it. Now, I can produce a good graphic with Mermaid in a matter of minutes instead of hours! This tool is going to be a boon to my efficiency and my communicative reach.
Creating Software with Modern Diagramming Techniques: Build Better Software with Mermaid
By Ashley Peacock
Copyright (c) 2023
The Pragmatic Bookshelf
ISBN13 9781680509830
Page Count: 128
Genre: Software Engineering
www.amazon.com