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

Length: 158 pages
Edition: 1
Language: English
Publisher: Pragmatic Bookshelf
Publication Date: 2023-03-14
ISBN-10: 1680509837
ISBN-13: 9781680509830
Sales Rank: #109570 (See Top 100 Books)

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

Acknowledgments
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
1. Document Your Domain
    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
2. 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
3. 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
4. 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 You’ve Learned
5. 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
6. Structure Your Components and Code
    Code Diagram
    Leverage Flowcharts for Complex Flows
    What You’ve Learned
7. 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
8. Visualize Code Flows
    Use Sequence Diagrams to Understand Class Interactions
    Define Loops
    Show Parallel Processes
    What You’ve Learned
9. 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
10. 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
11. 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
    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
12. What You’ve Learned
Bibliography