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.

Expand your professional vocabulary by learning to communicate with diagrams as easily and naturally as speaking or writing. This book will provide you with the skills and tools to turn ideas into clear, meaningful, and attractive diagrams in mere minutes, using nothing more complicated than text-based markup. You'll learn what kinds of diagrams are suited to each of a variety of use cases, from documenting your domain to understanding how complex code pieces together. Model your software's architecture, creating diagrams focused broadly or narrowly, depending on the audience. Visualize application and user flows, design database schemas, and use diagrams iteratively to design and refactor your application.

You'll be able to use technical diagramming to improve your day-to-day workflow. You will better understand the codebase you work in, communicate ideas more effectively and immediately with others, and more clearly document the architecture with C4 diagrams. Manually creating diagrams is cumbersome and time-consuming. You'll learn how to use text-based tools like Mermaid to rapidly turn ideas into diagrams. And You'll learn how to keep your diagrams up to date and seamlessly integrated into your engineering workflow. You'll be better at visualizing and communicating when you add diagrams to your standard vocabulary.

What You Need:

• A Mac or PC
• A GitHub account

Table of Contents

1. Document Your Domain

2. Enhanoe Your Domain Model

3. Visualize Application and User Flows

4. Model Your Architecture

5. Detail Your System·s Containers

6. Structure Your Components and Code

7. Design Database Schemas

8. Visualize Code Flows

9. Design and Refactor Your Applications

10. Render Diagrams Using Native Support

11. Create a Static Site with Mermaid Diagrams

12. What You·ve Learned

Who Should Read This Book?

This book is aimed primarily at engineers, of any level, who want to learn how to introduce diagrams into their development workflows. No prior knowledge is needed of any programming languages, and Mermaid’s syntax is incredibly simple and easy to pick up. Technical concepts are mentioned in the book, such as domain-driven design, but they all have a brief introduction and explanation.

If you want to become a better engineer, and in particular become better at conveying your thoughts and ideas, then you’re in the right place. There’s no easier way to convey your ideas, in my opinion, than a diagram.

What’s in This Book?

We’ll start out by introducing most of the key concepts used throughout the book: Mermaid and UML. We’ll cover a brief history of UML, get you set up with Mermaid, and even produce your first diagram!

We’ll then delve into the many use cases for diagramming, including:

• Chapter 1, ​Document Your Domain​, where you’ll be creating a domain model and we’ll introduce the concept of domain-driven design to those not familiar.
• You’ll learn how to easily explain different types of sequences in Chapter 3, ​Visualize Application and User Flows​, and Chapter 8, ​Visualize Code Flows​.
• Visualizing your architecture using the C4 Model in Chapter 4, ​Model Your Architecture​.
• Introducing diagramming to others, and ensuring your diagrams are easily accessible and up-to-date, in Chapter 10, ​Render Diagrams Using Native Support​, and Chapter 11, ​Create a Static Site with Mermaid Diagrams​.

What’s Not in This Book?

While I do briefly cover key technical concepts, this book isn’t going to go into deep levels of detail on anything except diagramming. For example, in Chapter 9, ​Design and Refactor Your Applications​, we’ll touch on concepts such as classes, interfaces, and inheritance, and I do provide brief introductions to them, but you’ll need to find other sources for a more in-depth understanding. In some cases, I recommend additional reading if you’re interested to learn more.

About the Author

Ashley Peacock is a staff engineer and architect working in the UK tech industry with over 10 years of experience. He's an avid user of diagrams, and a huge advocate for their power in conveying ideas, documenting architectures, and whiteboarding problems.

He has experience across the tech stack, with particular focus on backend technologies, having worked with C#, Ruby and PHP. He also has significant experience working with APIs and asychronous architectures, in particular working with Apache Kafka.