{ "version": "https://jsonfeed.org/version/1", "title": "Tools on enumerator.dev", "icon": "", "home_page_url": "https://enumerator.dev/", "feed_url": "https://enumerator.dev/feed.json", "items": [ { "id": "https://enumerator.dev/technical-diagrams-for-communication/", "title": "Technical Diagrams for Communication", "content_html": "

How many ways are there to draw the same diagram? Lots! It turns out. The screenshot below shows image search results for “google oauth login diagram.” Some of these diagrams are clear while others are cluttered and confusing.

\n

\n

Diagrams are a communication tool. Used well, they focus a conversation, communicate objectives, and enforce guidelines. Used poorly, they can derail conversations and result in frustration.

\n

The slides below are from a short workshop I gave on how I use diagramming in my technical proposals.

\n
\n
\n

Reasons to Draw

\n
    \n
  • Explore a problem
    • \n
  • Make a decision
    • \n
  • Share a solution
    • \n
\n\n
\n
\n
\n ❮\n 1 / 18\n ❯\n
\n
\n

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

\n

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.

\n\n
\n
\n
\n

Diagrams Create a Shared Mental Model of a System

\n\n
\n
\n
\n ❮\n 2 / 18\n ❯\n
\n
\n

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

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

What Makes a Good Diagram?

\n
    \n
  1. Follows a formula
    2. \n
  2. Minimal colour
    3. \n
  3. Clear visual hierarchy
    4. \n
  4. Incorporates time, relationships, & decisions as needed
    5. \n
\n\n
\n
\n
\n ❮\n 3 / 18\n ❯\n
\n
\n
    \n
  1. 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.
    2. \n
  2. Minimal colour. Too much colour is distracting. Only use colour to focus the eye on important details.
    3. \n
  3. Clear visual hierarchy. The reader should clearly see the important parts of the diagram on the first glance. Cut extra details.
    4. \n
  4. 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.
    5. \n
\n\n
\n
\n
\n

A Diagram Should Explain Itself

\n\n
\n
\n
\n ❮\n 4 / 18\n ❯\n
\n
\n

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.

\n\n
\n
\n
\n

Diagram to Explore a Problem

\n
    \n
  • Rough drawings
    • \n
  • Good for collaborating live and figuring out ideas
    • \n
  • Only make sense in the context of exploration
    • \n
\n\n
\n
\n
\n ❮\n 5 / 18\n ❯\n
\n
\n

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.

\n\n
\n
\n
\n

Example: OAuth Flow

\n

\n\n
\n
\n
\n ❮\n 6 / 18\n ❯\n
\n
\n

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.

\n\n
\n
\n
\n

Diagrams for Exploring are Not Diagrams for Communication

\n\n
\n
\n
\n ❮\n 7 / 18\n ❯\n
\n
\n

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.

\n\n
\n
\n
\n

Diagram to Make Decisions

\n
    \n
  • Communicate options
    • \n
  • Include time component when relevant
    • \n
  • Distinguish current and future state
    • \n
\n\n
\n
\n
\n ❮\n 8 / 18\n ❯\n
\n
\n

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.

\n\n
\n
\n
\n

OAuth Flow as Flow Chart

\n
flowchart LR\nUser -->|Enter credentials| Browser\nBrowser -->|POST /login| App[App Backend]\nApp -->|Verify password| DB[(Database)]\nApp -->|Set session cookie| Browser\nBrowser --> User
\n\n
\n
\n
\n ❮\n 9 / 18\n ❯\n
\n
\n

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

\n\n
\n
\n
\n

Auth Flow as Sequence Diagram

\n
sequenceDiagram\nactor User\nparticipant Browser\nparticipant App as App (Backend)\nparticipant DB as Database\nUser->>Browser: Enter email + password\nBrowser->>App: POST\nApp->>DB: Verify credentials\nDB-->>App: Valid\nApp-->>Browser: Set session cookie\nBrowser-->>User: Logged in
\n\n
\n
\n
\n ❮\n 10 / 18\n ❯\n
\n
\n

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.

\n\n
\n
\n
\n

OAuth Flow as Sequence Diagram

\n
sequenceDiagram\nactor User\nparticipant Browser\nparticipant App as App (Backend)\nparticipant Google\n\nUser->>Browser: Click "Sign in with Google"\nBrowser->>Google: Redirect to authorize\nGoogle->>User: Show consent screen\nUser->>Google: Authenticate + grant access\nGoogle-->>Browser: Redirect with auth code\nBrowser->>App: Send auth code\nApp->>Google: Exchange code for tokens\nGoogle-->>App: Return tokens\nApp-->>Browser: Set session cookie\nBrowser-->>User: Logged in
\n\n
\n
\n
\n ❮\n 11 / 18\n ❯\n
\n
\n

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.

\n\n
\n
\n
\n

An Artifact to Build From

\n
    \n
  • Document a desired state
    • \n
  • Can be used in Jira tickets
    • \n
  • Can change if you discover gotchas along the way
    • \n
\n\n
\n
\n
\n ❮\n 12 / 18\n ❯\n
\n
\n

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.

\n\n
\n
\n
\n

OAuth Artifact

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

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.

\n\n
\n
\n
\n

Four Types of Diagrams

\n\n
\n
\n
\n ❮\n 14 / 18\n ❯\n
\n
\n

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

\n\n
\n
\n
\n

Flow

\n

Use when a sequence of events can have alternative branches.

\n
flowchart LR\nStart([Start]) --> Decision{Condition met?}\nDecision -->|Yes| Path1[Do this]\nDecision -->|No| Path2[Do that]\nPath1 --> Stop([Stop])\nPath2 --> Stop
\n\n
\n
\n
\n ❮\n 15 / 18\n ❯\n
\n
\n

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

\n\n
\n
\n
\n

Entity Relationship Diagram

\n

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

\n
erDiagram\nUSER {\nint id\nstring email\nstring password_hash\n}\nSESSION {\nint id\nint user_id\nstring session_token\ndatetime expires_at\n}\nOAUTH_ACCOUNT {\nint id\nint user_id\nstring provider\nstring provider_user_id\n}\nUSER ||--o{ SESSION : has\nUSER ||--o{ OAUTH_ACCOUNT : has
\n\n
\n
\n
\n ❮\n 16 / 18\n ❯\n
\n
\n
\n

Network Architecture

\n

Use when describing how software systems interact over a network.

\n
architecture-beta\n\tgroup api(cloud)[API]\n\n\tservice db(database)[Database] in api\n\tservice disk1(disk)[Storage] in api\n\tservice disk2(disk)[Storage] in api\n\tservice server(server)[Server] in api\n\tdb:L -- R:server\n\tdisk1:T -- B:server\n\tdisk2:T -- B:db
\n\n
\n
\n
\n ❮\n 17 / 18\n ❯\n
\n
\n
\n

Resources

\n\n\n
\n
\n
\n ❮\n 18 / 18\n ❯\n
\n
\n
\n
\n\n", "date_published": "2026-08-07T00:00:00+00:00", "url": "https://enumerator.dev/technical-diagrams-for-communication/", "tags": ["tools"] }, { "id": "https://enumerator.dev/samuel-johnson-the-unexpected-grandfather-of-llms/", "title": "Samuel Johnson, the Unexpected Grandfather of LLMs", "content_html": "

As many people have I’ve been trying out a handful of LLMs to assist with coding. I’ve found them very useful tackling mundane tasks that might otherwise take me a few minutes, or at times hours, to accomplish on my own

\n

This reminds me of a good corruption of a Samuel Johnson quote:

\n
\n

The next best thing to knowing something is knowing where to find it.

\n
\n

The real quote is:

\n
\n

Knowledge is of two kinds. We know a subject ourselves, or we know where we can find information upon it. – https://www.samueljohnson.com/apocryph.html

\n
\n

Thank you to an LLM for uncovering this for me. To me, LLMs are the second kind of knowledge, and very useful for my day to day work. They let me focus on the big picture while taking care of the small details.

\n

Interestingly, the LLM I used also uncovered this quote:

\n
\n

The greatest part of a writer’s time is spent in reading, in order to write: a man will turn over half a library to make one book. https://www.samueljohnson.com/attentio.html

\n
\n

It is as if Johnson knew the environmental impact of LLMs before computers even existed. An LLM undoubtedly turns over half a library to write one good line of code.

\n", "date_published": "2025-01-31T00:00:00+00:00", "url": "https://enumerator.dev/samuel-johnson-the-unexpected-grandfather-of-llms/", "tags": ["tools","ai","llm"] } ] }