Technical Diagrams for Communication

Reasons to Draw

Explore a problem
Make a decision
Share a solution

❮ 1 / 18 ❯

I am going to talk about three different reasons to draw diagrams and why each reason requires a different thought process.

Diagrams are a powerful communication tool. If they are done wrong, they will send your audience off in the wrong direction and you’ll misunderstand each other. If they are done right, you’ll have a focused, productive conversation.

Diagrams Create a Shared Mental Model of a System

❮ 2 / 18 ❯

Put yourself in your audience’s position when you draw a diagram.

What are their goals when they read your diagram?
What context do they have that will affect how they read it?
What do you need from them when they see the diagram? Are you telling them how something works? Proposing a solution? Demonstrating a tradeoff?

What Makes a Good Diagram?

Follows a formula
Minimal colour
Clear visual hierarchy
Incorporates time, relationships, & decisions as needed

❮ 3 / 18 ❯

Following a formula makes it easy for your audience to understand the content. They will spend less time trying to take in the colours, symbols, and lines and instead see the whole picture.
Minimal colour. Too much colour is distracting. Only use colour to focus the eye on important details.
Clear visual hierarchy. The reader should clearly see the important parts of the diagram on the first glance. Cut extra details.
Incorporates time, relationships & decisions. Don’t use a single formula for every diagram. If time is an important factor, pick a structure that adds time on an axis. If relationships are important, use a diagram with symbols to indicate this aspect.

A Diagram Should Explain Itself

❮ 4 / 18 ❯

I have drawn many diagrams and when I step back I wonder, “What do these scribbles mean?” If you have to write extensive notes to explain a diagram, take another pass at it. Try using a different diagramming syntax or cut out unnecessary elements.

Diagram to Explore a Problem

Rough drawings
Good for collaborating live and figuring out ideas
Only make sense in the context of exploration

❮ 5 / 18 ❯

Diagrams for exploring problems are the kind that I make when I’m pairing with a group to solve a problem or hashing something out on a notepad for myself. These diagrams only make sense in the moment and only to the people present.

Example: OAuth Flow

A rough hand-drawn sketch titled “Authentication Flow”, with boxes for User, /login, Backend, OAuth Provider, and OAuth Validate joined by arrows

❮ 6 / 18 ❯

Here’s an example of a very rough diagram of an OAuth flow. This is the kind of diagram I’d draw to understand the key elements involved. But this diagram is useless for communicating the components and sequences involved.

Diagrams for Exploring are Not Diagrams for Communication

❮ 7 / 18 ❯

Draw lots of diagrams! Exploring problems with diagrams is great. But they are for a small audience. These diagrams are not good for communicating to a broader audience.

Diagram to Make Decisions

Communicate options
Include time component when relevant
Distinguish current and future state

❮ 8 / 18 ❯

Drawing to make decisions means you have an external audience. This is where it is important to think about your audience’s context and pick the right visual language.

OAuth Flow as Flow Chart

flowchart LR
User -->|Enter credentials| Browser
Browser -->|POST /login| App[App Backend]
App -->|Verify password| DB[(Database)]
App -->|Set session cookie| Browser
Browser --> User

❮ 9 / 18 ❯

The flow chart in this example works for a simple flow but makes the details of OAuth very hard for an audience to understand.

Auth Flow as Sequence Diagram

sequenceDiagram
actor User
participant Browser
participant App as App (Backend)
participant DB as Database
User->>Browser: Enter email + password
Browser->>App: POST
App->>DB: Verify credentials
DB-->>App: Valid
App-->>Browser: Set session cookie
Browser-->>User: Logged in

❮ 10 / 18 ❯

Here’s the basic auth flow as a sequence diagram. There is a clear syntax. You don’t even have to read “user” to know that the stick person is a human, and the x axis clearly distinguishes components while the y axis delineates time.

OAuth Flow as Sequence Diagram

sequenceDiagram
actor User
participant Browser
participant App as App (Backend)
participant Google

User->>Browser: Click "Sign in with Google"
Browser->>Google: Redirect to authorize
Google->>User: Show consent screen
User->>Google: Authenticate + grant access
Google-->>Browser: Redirect with auth code
Browser->>App: Send auth code
App->>Google: Exchange code for tokens
Google-->>App: Return tokens
App-->>Browser: Set session cookie
Browser-->>User: Logged in

❮ 11 / 18 ❯

And here’s the OAuth flow. You can now look at the two side by side and clearly see the difference. If we were building a product and wanted to decide between Google OAuth or basic auth, these two diagrams could help us understand the tradeoffs.

An Artifact to Build From

Document a desired state
Can be used in Jira tickets
Can change if you discover gotchas along the way

❮ 12 / 18 ❯

Diagrams as artifacts are like blueprints for projects. A good diagram can be referenced over the course of a project and shared with the team. Nothing is certain in software, though! It’s good practice to update artifacts to keep a shared mental model of the system.

OAuth Artifact

sequenceDiagram
    participant User
    participant Browser
    participant App as App (Backend)
    participant Google

    User->>Browser: Click "Sign in with Google"
    Browser->>App: GET /auth/google
    App-->>Browser: 302 Redirect to Google authorize URL<br/>(client_id, redirect_uri, scope, state, response_type=code)
    Browser->>Google: GET /o/oauth2/v2/auth
    Google-->>Browser: Show account picker + consent screen
    User->>Google: Authenticate + grant consent
    Google-->>Browser: 302 Redirect to redirect_uri<br/>(authorization code, state)
    Browser->>App: GET /auth/google/callback?code=...&state=...
    Note over App: Validate state (CSRF check)
    App->>Google: POST /token<br/>(code, client_id, client_secret, redirect_uri, grant_type=authorization_code)
    Google-->>App: access_token, id_token (JWT), refresh_token
    Note over App: Verify id_token signature + claims<br/>(read sub, email, name)
    Note over App: Find or create user, establish session
    App-->>Browser: Set session cookie, redirect to app
    Browser-->>User: Logged in

❮ 13 / 18 ❯

As an artifact, the OAuth flow has more detail and notes on each interaction. You could reference this diagram if you needed to sort out the requirements to implement a part of this flow.

Four Types of Diagrams

❮ 14 / 18 ❯

I used sequence diagrams today as an example. There are many other diagramming syntaxes. Here are four more that I find useful.

Flow

Use when a sequence of events can have alternative branches.

flowchart LR
Start([Start]) --> Decision{Condition met?}
Decision -->|Yes| Path1[Do this]
Decision -->|No| Path2[Do that]
Path1 --> Stop([Stop])
Path2 --> Stop

❮ 15 / 18 ❯

Don’t go overboard on syntax. Stick to simple diagram syntax that your audience will understand.

Entity Relationship Diagram

Use when entities (often database tables) have relationships to one another.

erDiagram
USER {
int id
string email
string password_hash
}
SESSION {
int id
int user_id
string session_token
datetime expires_at
}
OAUTH_ACCOUNT {
int id
int user_id
string provider
string provider_user_id
}
USER ||--o{ SESSION : has
USER ||--o{ OAUTH_ACCOUNT : has

❮ 16 / 18 ❯

Network Architecture

Use when describing how software systems interact over a network.

architecture-beta
	group api(cloud)[API]

	service db(database)[Database] in api
	service disk1(disk)[Storage] in api
	service disk2(disk)[Storage] in api
	service server(server)[Server] in api
	db:L -- R:server
	disk1:T -- B:server
	disk2:T -- B:db

❮ 17 / 18 ❯

Resources

❮ 18 / 18 ❯