Creating Software with Modern Diagramming Techniques

by Ashley Peacock

Diagrams communicate relationships more directly and clearly than words ever can. Using only text-based markup, create meaningful and attractive diagrams to document your domain, visualize user flows, reveal system architecture at any desired level, or refactor your code. With the tools and techniques this book will give you, you’ll create a wide variety of diagrams in minutes, share them with others, and revise and update them immediately on the basis of feedback. Adding diagrams to your professional vocabulary will enable you to work through your ideas quickly when working on your own code or discussing a proposal with colleagues.

Genres: Programming, Software, Technology, Computer Science, Design

150 pages, ebook

Published February 1, 2023

Reviews

[TWJ Spencer · Rating 5 out of 5]

Great introduction to diagramming and Mermaid.

I really enjoyed this book. It gives a nice overview of a whole range of topics relating to software architecture including:
- domain modelling with Domain Driven Design
- Class Diagramming
- Flow Diagrams
- Schema Diagrams
- C4 architecture

There is even a section on how to deploy the diagrams to a website. I got a great overview of how to use Mermaid and the way in which we can use diagrams to help illustrate ideas effectively.
Highly recommended!

[Scott Pearson · Rating 5 out of 5]

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.

[Adam Wan · Rating 5 out of 5]

This is definitely a great book explaining how to use the modern methodologies (C4, UML) to illustrate the ideas using MermaidJS (Diagram as Code).

The book itself is absolutely amazing with a lot of detailed examples and clear workflow.

[Slava · Rating 5 out of 5]

Clean and concise examples, to the point and without fluff.

[Cornelius Tyranade · Rating 5 out of 5]

Pretty good content! Make diagraming fun again!

[Oscar Robinson · Rating 5 out of 5]

A succinct but thorough overview of software diagramming. The book does a great job of giving clear examples in the software engineering workflow where diagramming can be usefully applied. I’m already making far more diagrams as a result and find it’s becoming much easier to communicate my ideas to others.

[Ken Chew · Rating 4 out of 5]

A good introductory book to diagram as code in general.

Plantuml had been around for a while but still there’s a level of friction to get team to adopt it.

This book not only introduces mermaid but does it in the context of diagramming and documenting.

Not sure how far mermaid will go but the diagramming part is definitely worth reading for software professionals.

[Fábio Fortkamp · Rating 2 out of 5]

Nice little book on diagramming, that gave me some practical ideas. However, this books feels like it does not belong on PragProg's price range. I've read deep, amazing books from this wonderful publisher, and Creating Software with Modern Diagramming Techniques costs the same but it's like a long blog post packed into a PDF (it is indeed very short). I appreciate the clear writing style and the praise for diagramming (with which I agree), but this feels like a glorified version of the official Mermaid docs.

I think the decision to not include any programming was wrong; the document would be much more valuable with some sort of iteration between drawing diagrams and code. For instance, on the chapter on refactoring, the author could pick a real example and then show how he made sense of the mess with diagram, followed by actual code changes.

I wish I could extract more from this book, but there isn't much to learn.

[Héctor Iván Patricio Moreno · Rating 4 out of 5]

Es un muy buen libro que resalta la importancia de las ayudas visuales para desarrollar software, específicamente en forma de diagramas. Presenta una herramienta llamada Mermaid que permite hacer diagramas bonitos con código. En el libro se habla de diagramas de clase, de flujo, de secuencia y entidad relación.

Lo que más me gustó del libro es que tiene un enfoque pragmático hacia la documentación y un uso liberal de los tipos de diagramas, de hecho, me atrevería a decir que ninguno de los diagramas que acabo de mencionar se usa de manera tradicional. Por ejemplo, el diagrama de clases se usa para documentar el modelo de un sistema en vez de una estructura de clases tradicional. También explica cómo hacer un conjunto de diagramas para la arquitectura basado en C4.

Si estás aprendiendo a documentar y a usar diagramas, es un excelente recurso para arrancar.

[Srinivasan Nanduri · Rating 4 out of 5]

If you're a developer or architect aiming to quickly adopt diagram-as-code practices—with version control, collaboration, and tools like C4 in mind—Creating Software with Modern Diagramming Techniques is a strong, focused introduction. It's short, sharp, and actionable.

However, if you're looking for a deep dive into UML or rich architectural theory, you may want to pair it with more comprehensive titles.

[Artur Skowroński · Rating 4 out of 5]

I needed the book for the Mermaid syntax for UML + C4 with some practical examples. It was worth both the time and money, as it helped me organize and structure my knowledge from the lecture, now I will feel better informed getting myself through official documentation.

Nothing groundbreaking, but tad useful.

[Nicola · Rating 4 out of 5]

The book makes different examples of diagrams by using mermaid. It's not just a book about mermaid itself, but it talks about diagramming techniques more in general. In some parts I think the book could be shorter than it already is.
It's most likely a useful book to keep as a reference, and for that reason I'd suggest buying the ebook version of it.

[Yves Goldberg · Rating 4 out of 5]

good intro to mermaid

[Illia · Rating 4 out of 5]

The main benefit for me out of this book is that it introduces me to mermaid; the rest of the book is mostly useless.