Table of Contents
About the book
About the author
I Visualise
We have a failure to communicate
What happened to SSADM, RUP, UML, etc?
A lightweight approach
Moving fast requires good communication
Draw one or more diagrams
Where do we start?
Some examples
Common problems
The hidden assumptions of diagrams
A shared vocabulary
Common abstractions over a common notation
Static structure
Components vs code?
Modules and subsystems?
Microservices?
Serverless?
Platforms, frameworks and libraries?
Create your own shared vocabulary
The C4 model
Hierarchical maps of your code
Level 1: System Context diagram
Intent
Structure
Elements
Interactions
Motivation
Audience
Required or optional?
Level 2: Container diagram
Intent
Structure
Elements
Interactions
Motivation
Audience
Required or optional?
Level 3: Component diagram
Intent
Structure
Elements
Interactions
Motivation
Audience
Required or optional?
Level 4: Code-level diagrams
Intent
Structure
Motivation
Audience
Required or optional?
Notation
Titles
Keys and legends
Elements
Lines
Layout
Orientation
Acronyms
Quality attributes
Diagram scope
Listen for questions
Diagrams must reflect reality
The model-code gap
Technology details on diagrams
Would you code it that way?
Other diagrams
Architectural view models
System Landscape
User interface mockups and wireframes
Business process and workflow
Domain model
Runtime and behaviour
Infrastructure
Deployment
And more
II Document
Software documentation as a guidebook
The code doesn't tell the whole story
Our duty to deliver documentation
Lightweight, supplementary documentation
1. Maps
2. Sights
3. History and culture
4. Practical information
Describe what you can't get from the code
Product vs project documentation
Keeping documentation up to date
Documentation length
Context
Intent
Structure
Motivation
Audience
Required
Functional Overview
Intent
Structure
Motivation
Audience
Required
Quality Attributes
Intent
Structure
Motivation
Audience
Required
Constraints
Intent
Structure
Motivation
Audience
Required
Principles
Intent
Structure
Motivation
Audience
Required
Software Architecture
Intent
Structure
Motivation
Audience
Required
Code
Intent
Structure
Motivation
Audience
Required
Data
Intent
Structure
Motivation
Audience
Required
Infrastructure Architecture
Intent
Structure
Motivation
Audience
Required
Deployment
Intent
Structure
Motivation
Audience
Required
Operation and Support
Intent
Structure
Motivation
Audience
Required
Development Environment
Intent
Structure
Motivation
Audience
Required
Decision Log
Intent
Structure
Motivation
Audience
Required
III Tooling
Sketches, diagrams, models and tooling
Sketches
Diagrams
Models
Reverse-engineering the software architecture model
Architecture description languages
Structurizr
Minimise the model-code gap
The C4 model with other notations and tools
Boxes and lines
UML (with a modeling tool)
UML (with PlantUML)
Exploring your software architecture model
Static structure
Dependency maps
Component size or complexity
Other ways to explore
Appendix A: Financial Risk System
Background
Functional Requirements
Non-functional Requirements