Build Better Software with Mermaid
Ashley Peacock
Sinossi
Diagrams communicate relationships more directly and clearly than words ever could. Create meaningful and attractive diagrams to document your domain, visualize user flows, show system architecture at any level, or refactor your code using only text-based markup. With the tools and techniques this book gives you, you'll create a variety of diagrams in minutes, share them with others, and instantly revise and update them based on feedback. Adding diagrams to your professional vocabulary will help you quickly work through ideas when you're 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 you do in speech and writing. This book gives you the skills and tools to turn your ideas into clear, meaningful, and attractive diagrams in minutes, using nothing more complicated than text-based markup. Learn what types of diagrams are appropriate for a variety of use cases, from documenting your domain to understanding how complex code is put together. Model the architecture of your software and create diagrams with a broad or narrow focus, depending on your audience. Visualize application and user flows, design database schemas, and use diagrams iteratively to design and refactor your application.
You will be able to use technical diagrams to improve your daily workflow. You'll better understand the codebase you're working in, communicate ideas more effectively and immediately with others, and document the architecture more clearly with C4 diagrams. Creating diagrams manually is tedious and time-consuming. You'll learn how to quickly turn ideas into diagrams with text-based tools like Mermaid. And you'll learn how to keep your diagrams up to date and seamlessly integrated into your technical workflow. Adding diagrams to your standard vocabulary will help you visualize and communicate better.
contents
- 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
- Determine The Important Entities
- Document Our First Relationship
- Define Associations
- Define Composite Relationships
- Define Aggregate Relationships
- Decide Between Association, Aggregation & Composition
- Document Your Own Domain
- What We’ve Learned
- Enhance Your Domain Model
- Define Inheritance
- Describe Relationships
- Add Multiplicity
- Improve Readability
- Enrich Nodes With Links
- Enhance Your Domain Model
- What We’ve Learned
- Visualise Application & User Flows
- Define Actors & Participants
- Add Our First Interaction
- Show Branching Logic
- Display Asynchrous Messages
- Display Length Of Interactions With Activations
- Add Additional Information With Notes
- Annotate Your Diagram With Sequence Numbers
- Create Dropdown Menus
- Visualise Your Own Application Flow
- What We’ve Learned
- Model Your Architecture
- Using The C4 Model
- Creating A System Context Diagram
- Add Nodes
- Connect Nodes
- Add Some Style
- Create Your Own System Context Diagram
- What We’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 We’ve Learned
- Structure Your Components & Code
- Code Diagram
- Leverage Flowcharts For Complex Flows
- What We’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
- Finalise Streamy’s ERD
- Design Your Database Schema
- What We’ve Learned
- Visualise Code Flows
- Use Sequence Diagrams To Understand Class Interactions
- Define Loops
- Show Parallel Processes
- What We’ve learned
- Design & Refactor Your Applications
- Identify Refactoring Opportunities With Class Diagrams
- Define Classes
- Show Dependencies With Relationships
- Refactor The Classes
- Introduce A Request Class
- Define Interfaces
- Create A Class Diagram
- What We’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 We’ve learned
- Create A Static Site With Mermaid Diagrams
- Devise A Plan Of Action
- Learn The Basics Of A GitHub Action
- Start By Defining The Events That Trigger The Action
- Checkout The Repository’s Code
- Convert Mermaid Markup To SVGs In Markdown
- Build Jekyll Artifacts
- Deploy To GitHub Pages
- Run The Action
- What We’ve learned
- What We’ve Learned