Creating Software with Modern Diagramming Techniques

Build Better Software with Mermaid

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.

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.

• A Mac or PC
• A GitHub account

• Errata, typos, suggestions

• Source Code (zip file)

Releases:

• P1.0 2023/02/14
• B4.0 2023/01/06
• B3.0 2022/11/29
• B2.0 2022/11/15

• Preface
  • Who Should Read This Book?
  • What’s in This Book?
  • What’s Not in This Book?
  • How to Read This Book
  • Online Resources
• Introduction
  • Diagramming Techniques
  • Diagramming Tools
  • Creating Diagrams
  • Using the Command Line
• Document Your Domain excerpt
  • Determine the Important Entities
  • Document Our First Relationship
  • Define Associations
  • Define Composite Relationships
  • Define Aggregate Relationships
  • Decide Between Association, Aggregation, and Composition
  • Document Your Own Domain
  • What You’ve Learned
• Enhance Your Domain Model
  • Define Inheritance
  • Describe Relationships
  • Add Multiplicity
  • Add a Title
  • Improve Readability
  • Enrich Nodes with Links
  • Enhance Your Domain Model
  • What You’ve Learned
• Visualize Application and User Flows
  • Define Actors and Participants
  • Add Our First Interaction
  • Show Branching Logic
  • Display Asynchronous Messages
  • Display Length of Interactions with Activations
  • Add Additional Information with Notes
  • Annotate Your Diagram with Sequence Numbers
  • Create Dropdown Menus
  • Visualize Your Own Application Flow
  • What You’ve Learned
• Model Your Architecture
  • Using the C4 Model
  • Creating a System Context Diagram excerpt
  • Add Nodes
  • Connect Nodes
  • Add Some Style
  • Create Your Own System Context Diagram
  • What You’ve Learned
• Detail Your System’s Containers
  • Define the First Two Containers
  • Create Clear Boundaries with Subgraphs
  • Add Supporting Systems
  • Improve Readability with Link Lengths
  • Display Asynchronous Interactions
  • Additional Arrow Types
  • Create Your Own Container Diagram
  • What You’ve Learned
• Structure Your Components and Code
  • Code Diagram
  • Leverage Flowcharts for Complex Flows
  • What You’ve Learned
• Design Database Schemas
  • Use Entity Relationship Diagrams
  • Define Our First Entity
  • Relate Entities
  • Add Zero-to-Many Relationships
  • Enrich Schemas with Keys
  • Comment Your Columns
  • Define Zero-or-One Relationships
  • Describe Non-identifying Relationships
  • Finalize Streamy’s ERD
  • Design Your Database Schema
  • What You’ve Learned
• Visualize Code Flows
  • Use Sequence Diagrams to Understand Class Interactions
  • Define Loops
  • Show Parallel Processes
  • What You’ve Learned
• Design and Refactor Your Applications
  • Define Classes
  • Show Dependencies with Relationships
  • Refactor the Classes
  • Introduce a Request Class
  • Define Interfaces
  • Create a Class Diagram
  • What You’ve Learned
• Render Diagrams Using Native Support
  • Leverage Native Mermaid Integrations
  • Render Mermaid Within Markdown Files
  • Where Should You Include Diagrams?
  • What About Websites Without Native Support?
  • Keep Diagrams Up-to-Date
  • Render a Diagram on GitHub
  • What You’ve Learned
• Create a Static Site with Mermaid Diagrams
  • Devise a Plan of Action excerpt
  • Learn the Basics of a GitHub Action
  • Start by Defining the Events That Trigger the Action
  • Check Out the Repository’s Code
  • Convert Mermaid Markup to SVGs in Markdown
  • Build Jekyll Artifacts
  • Deploy to GitHub Pages
  • Run the Action
  • Render Diagrams on Page Load
  • What You’ve Learned
• What You’ve Learned

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.