Expand your software engineering vocabulary by learning to communicate with diagrams as easily and naturally as speaking or writing.
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.
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.
Reviews
"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." - via Goodreads
"This book on diagramming lays out a pragmatic and step by step approach to learning how to diagram with Mermaid. It starts out with super simple examples and slowly layers on how to add in complexity (and what type of diagram is suitable for what types of situations)." - via Amazon
What You Need:
• A Mac or PC
• A GitHub account
Author(s): Ashley Peacock
Edition: 1
Publisher: Pragmatic Bookshelf
Year: 2023
Language: English
Commentary: Publisher's PDF
Pages: 158
City: Raleigh, NC
Tags: Software Engineering; GitHub; Markdown; Software Architecture; UML; Flowcharts; Mermaid
Cover
Table of Contents
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
