When to Use Diagrams

Not everything needs a diagram. Not everything should be prose. The decision of when to visualize and when to write is a skill most technical writers never develop intentionally — they either diagram everything (producing cluttered, redundant visuals) or diagram nothing (forcing the reader to mentally reconstruct spatial relationships from text). The rule is straightforward: words explain reasoning and processes. Diagrams explain relationships and flows. Tables compare options. Knowing which tool to reach for depends on what kind of information you are communicating.

The Core Principle

Different types of information have natural formats. Using the wrong format makes the reader work harder than necessary.

Information type        Best format
─────────────────────────────────────────────────
How A connects to B     Diagram
Why we chose A over B   Prose
What happens in order   Numbered list or flowchart
Comparing A, B, and C   Table
What a term means       Prose (inline or glossary)
How data flows          Diagram
What the constraints    Prose with bullet list
What the config is      Code block
What changed            Diff or changelog

The test is not "would a diagram look nice here?" The test is "does the reader need to understand spatial relationships, connections, or flow?" If yes, draw it. If the reader needs to understand reasoning, motivation, or nuance, write it.

When Diagrams Help

Relationships Between Components

When you are explaining how things connect — services to databases, modules to each other, users to systems — a diagram communicates in seconds what prose takes paragraphs to describe.

Prose version (hard to follow):
  "The web application sends requests to the API gateway. The API
   gateway routes requests to one of three backend services:
   the user service, the order service, or the inventory service.
   The user service connects to a PostgreSQL database. The order
   service connects to the same PostgreSQL database and also to
   a Redis cache. The inventory service connects to a separate
   MongoDB instance and publishes events to a Kafka topic that
   the order service consumes."

What this is really describing:
  A system with 6 components and 8 connections between them.
  That is a diagram, not a paragraph.

The prose version forces the reader to build the mental picture themselves. They have to track which service connects to what, hold multiple relationships in working memory, and hope they assembled the picture correctly. A diagram shows the picture directly.

Data Flow & Request Paths

When data moves through a system — a request being processed, a message passing through a pipeline, a file being transformed — the spatial nature of the flow maps naturally to a visual.

Questions that diagrams answer well:

  "What happens when a user clicks 'submit'?"
  "How does a message get from the producer to the consumer?"
  "Where does the data go after it's ingested?"
  "What services are in the critical path of this request?"

For each of these, the reader needs to see the path. Prose can describe it, but the reader has to mentally trace the path from words. A diagram lets them see it directly.

State Machines & Decision Logic

When something can be in multiple states and transitions between them based on conditions, a state diagram or flowchart communicates the logic more clearly than prose or code.

Prose version:
  "An order starts in the 'pending' state. When payment is confirmed,
   it moves to 'paid.' From 'paid,' it moves to 'shipped' when the
   warehouse confirms dispatch. If payment fails, it moves from
   'pending' to 'failed.' A 'shipped' order becomes 'delivered' when
   the carrier confirms delivery. A 'paid' order can be 'cancelled'
   if the customer requests it before shipping."

What this is really describing:
  5 states with 5 transitions and 2 conditional branches.
  That is a state diagram.

Network Topology & Infrastructure

Any time you need to convey where things are physically or logically located — which services run in which VPC, what sits behind the load balancer, where the firewall rules apply — use a diagram. Prose descriptions of network architecture are nearly impossible to follow.

When Diagrams Do Not Help

Explaining "Why"

Diagrams show structure and flow. They do not explain reasoning. If you need to explain why a decision was made, why an architecture was chosen, or why a constraint exists, write prose.

Bad use of a diagram:
  A box labeled "PostgreSQL" with an arrow to a box labeled "Chosen
  because of ACID compliance, mature tooling, and team familiarity"

  [This is not a relationship or a flow. This is an argument.
   Arguments belong in prose.]

Good use of prose:
  "We chose PostgreSQL over MongoDB for three reasons: we need
   ACID transactions for financial data, the team has 5+ years
   of PostgreSQL experience, and our existing tooling (pgBackRest,
   PgBouncer) is PostgreSQL-specific."

Sequential Instructions

Step-by-step instructions belong in numbered lists, not flowcharts. A flowchart adds visual overhead without adding clarity when the path is linear.

Unnecessary flowchart:
  [Start] → [Run tests] → [Build image] → [Push to registry] → [Deploy]

  [This is a straight line. A numbered list is simpler.]

Better as a list:
  1. Run the test suite
  2. Build the Docker image
  3. Push to the container registry
  4. Deploy to production

Flowcharts earn their complexity when there are branches, conditions, or loops. A linear sequence should be a numbered list.

Comparing Options

When you need to compare three database options across six criteria, a table is the right format. Not a diagram, not prose paragraphs.

Table (easy to compare):

  Feature        PostgreSQL    MongoDB       DynamoDB
  ────────────────────────────────────────────────────
  Transactions   Full ACID     Multi-doc     Limited
  Scaling        Vertical      Horizontal    Horizontal
  Query lang     SQL           MQL           PartiQL
  Hosting        Self/managed  Self/managed  Managed only
  Team exp       High          Medium        Low
  Cost (est.)    $500/mo       $800/mo       $300/mo

Prose (hard to compare):
  "PostgreSQL offers full ACID transactions and uses SQL. It scales
   vertically. Our team has high experience with it and it would cost
   about $500/month. MongoDB offers multi-document transactions..."

  [The reader has to mentally build the table from paragraphs.
   Just give them the table.]

Definitions & Terminology

Glossary entries, term definitions, and conceptual explanations are prose. A diagram of "what is a microservice" is not useful. A paragraph explaining it is.

The Combination Approach

The best technical documents use diagrams and prose together, each doing what it does best.

Effective pattern:

  1. Diagram showing the system architecture (relationships)
  2. Prose explaining why this architecture was chosen (reasoning)
  3. Table comparing the options that were considered (comparison)
  4. Numbered list of steps to deploy it (instructions)

Each format handles the type of information it is best suited for. The diagram does not try to explain reasoning. The prose does not try to show topology. The table does not try to narrate a sequence.

Prose That References Diagrams

When you use both, the prose should reference the diagram specifically. Do not assume the reader will look at the diagram and extract the right insight.

Weak reference:
  "See the diagram above for the architecture."

Strong reference:
  "The API gateway (shown at the top of the architecture overview)
   is the single entry point for all client traffic. It routes to
   the three backend services based on the URL prefix: /users goes
   to the user service, /orders to the order service, and /inventory
   to the inventory service."

The strong reference tells the reader what to look for in the diagram and adds information the diagram cannot convey (the routing rules).

Choosing the Right Diagram Type

When you have decided a diagram is warranted, choose the type that matches the information.

What you are showing              Diagram type
───────────────────────────────────────────────────────
Components and how they connect   Architecture / box-and-arrow
Data flowing through a system     Sequence diagram or data flow
States and transitions            State machine diagram
Time-ordered events               Timeline or sequence diagram
Hierarchical structure            Tree diagram
Decision logic with branches      Flowchart
Class or entity relationships     ER diagram or class diagram
Deployment topology               Infrastructure / deployment diagram

Using the wrong diagram type is almost as bad as not using a diagram at all. A sequence diagram for something that is really a state machine forces the reader to reconstruct the states from the sequences.

Diagram Anti-Patterns

The Everything Diagram

One diagram showing every component, every connection, every database, every queue, every external service. These diagrams are technically accurate and practically useless. The reader cannot find the information they need because it is buried in visual noise.

Signs your diagram is too complex:

  - More than 10-12 boxes
  - Lines crossing multiple times
  - Labels that need to be tiny to fit
  - You need to zoom in to read anything
  - It tries to answer multiple questions

The fix: multiple simple diagrams, each at one level of abstraction and answering one question.

Defaulting to diagrams for everything. Not every section needs a visual. Use diagrams when spatial relationships or flow matter. Use prose when reasoning matters.
Using prose to describe what a diagram should show. If you find yourself writing "A connects to B, which connects to C, which connects to D," stop writing and draw it.
Creating one diagram per document. Different sections may need different diagram types at different abstraction levels. Multiple focused diagrams beat one overloaded diagram.
Skipping labels on arrows. An unlabeled arrow is ambiguous. Label every connection with the relationship it represents.
Using flowcharts for linear processes. If there are no branches, use a numbered list. Flowcharts are for branching logic.
Putting reasoning into diagrams. Diagrams show structure. Prose explains decisions. Do not try to make a diagram do both.
Never updating diagrams. An outdated diagram is worse than no diagram because it actively misleads. If the system changes, update the diagram or remove it.

Key Takeaways

Diagrams explain relationships and flow. Prose explains reasoning and motivation. Tables compare options. Use the format that matches the information type.
If you are describing how A connects to B connects to C, draw it. If you are explaining why, write it.
Multiple simple diagrams beat one complex diagram. Each diagram should answer one question.
Label everything in a diagram: boxes, arrows, groupings. Ambiguous visuals are worse than no visuals.
The best documents combine diagrams, prose, tables, and lists, each handling the type of information it is best at.
If a diagram does not add information beyond what the prose provides, delete it.