Creating Software with Modern Diagramming Techniques: Build Better Software with Mermaid

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.

This book on diagramming lays out a pragmatic and step by step approach to learning how to diagram with Mermaid. It starts out with super simple examples and slowly layers on how to add in complexity (and what type of diagram is suitable for what types of situations). Each chapter gives you a strong foundation so that as you progress you are building on previous examples and ends with a quick summary to reinforce new concepts. Everything is based on domain-driven design, and while it isn't the focus of the book, you get a sense of the framework through the practical examples.Game changer for people like me who are used to hand drawn diagrams. Also has huge business benefit to bring engineering concepts to less technical folks (like product managers, business stakeholders, clients etc.) for alignment and to ensure requirements are understood.

This book should be part of the welcome package of any new tech hire. If an organization can move with Mermaid, it can move really fast.Prototyping, modeling, architecting - basically the mermaid diagramming shorthand is a language that makes expressing complex technical ideas a breezy process.

Very insightful book to develop new skills and enhance your career with diagramming!

I thought this was going to be an insightful book about why it is so critical to use diagrams for communicating technical aspects of software and architecture. Unfortunately, it is just a very basic 'tutorial' of a tool - that isn't even very good at what it does - that skims through important concepts and just teaches the syntax of Mermaid. The UML aspects that it covers are probably taught in the first two weeks of a CS-1 course with OOP. The C4 part, in any decent basic Software Architecture course.With respect to the tool, it has many quirks that I cannot ignore, like using filled arrowheads for inheritance instead of empty ones, or not using the guillomets for entities' stereotypes.