A system analyst quickly develops a temptation to explain everything in prose. Describe the process in words, the logic as a list, integrations in a paragraph, data in a table. Up to a point, that even works. But as soon as the system becomes slightly more complex, text stops holding the whole picture together.

That is when diagrams enter the work.

Not as documentation decoration, and not as ceremony for its own sake. But as a way to make the system surveyable. A diagram is not good because it looks pretty. It is good when, after looking at it, people start to agree on how a slice of the system is structured, where its boundaries are, and what actually matters in it.

The problem is that a diagram can just as easily become useless if you draw it without a clear goal. One of the most common mistakes is trying to explain everything at once in a single picture: process, roles, architecture, data, integrations, and internal system logic. Such a diagram often looks impressive, but reads poorly and barely answers any single concrete question.

A good diagram works differently. It does not try to show everything. It shows only what matters for one task.

That is why one diagram is almost never enough.

Because different diagrams answer different questions. One helps you see how a process flows. Another shows how systems interact. A third shows how data is structured. A fourth shows how an object changes state. A fifth shows where the system’s boundaries run and what parts it consists of.

In practice, this is fairly simple. If you need to explain how a request is approved, a process view is usually best. If you need to show which services take part in order placement and in what order they are called, you need a different lens. If the conversation is about how order, customer, payment, and delivery relate, that is not really a process story at all—it is a data story. If you need to understand why an object’s status cannot jump from one state to another, you are better off looking not at BPMN or a sequence diagram, but at a state diagram.

So the same system can be described with several diagrams, and that is normal.

Take order placement as an example. BPMN will show how the process moves step by step: who creates the order, where payment happens, when confirmation occurs, where branches appear. A sequence diagram shows something else: which systems participate in the scenario, who sends which request, when a response arrives, where an error or an external call appears. An ER diagram shows the data structure: which entities exist at all, and how Order, Payment, Delivery, and Customer are related. A state diagram shows how the order itself lives over time: Draft, Confirmed, Paid, Cancelled, Shipped.

These are not competing ways to describe the system. They are simply different cross-sections of the same system.

To me, this is one of the most useful ideas for an analyst. A diagram is not “documentation in general.” It is an answer to a specific question. Until the question is clear, the diagram almost always turns out muddy. Once the question is clear, it also becomes clearer what you should actually draw.

If you boil it down, the most common diagrams in systems analysis usually look like this.

BPMN is for when you want to show a process. What happens, in what sequence, where there are forks, who owns each step. It is especially helpful where you need to unpack business logic into steps and see the process as structure, not as a story.

[Start]
   ↓
User starts validation
   ↓
Add-in reads model elements
   ↓
Add-in validates parameters against rules
   ↓
Any issues?
 ┌───────────────┴───────────────┐
 Yes                              No
 ↓                                ↓
Show error list                Show message
 ↓                             "No issues found"
User fixes the model                ↓
in Revit                         [End]
 ↓
Re-run validation
   ↓
[End]

What this kind of diagram gives you: a quick view of the overall flow, decision points, and where the user sits in the process.

A sequence diagram is for when interaction over time matters. Who sends which request, who responds, what is called next, where the scenario begins and ends. It is a very practical diagram for integrations, APIs, and distributed flows.

If you frame the task as interactions between components, you are already in Sequence Diagram territory.

Here we care about who talks to whom and in what order.

User
    |
    | clicks "Verify model"
    v
Revit Plugin UI
    |
    | starts validation
    v
Validation Engine
    |
    | requests elements
    v
Revit Model
    |
    | returns elements and parameters
    v
Validation Engine
    |
    | fetches validation rules
    v
Rules Config / External API
    |
    | returns rules
    v
Validation Engine
    |
    | builds error list
    v
Revit Plugin UI
    |
    | shows result
    v
User

What this diagram gives you: it is no longer the business process, but the technical interaction between the user, the add-in, the model, and the source of validation rules.

An ER diagram is for when the subject is data. Which entities exist, how they relate, where the relationship is one-to-many, where it is mandatory or optional. That is no longer about process steps; it is about the data model everything rests on.

If you frame the task in terms of data, you are already in ERD territory—or at least in a simple entity model.

Here what matters is not who clicks what or in which order calls happen, but which entities exist in the solution at all.

Project
 └── contains → Element
                  ├── belongs to → Category
                  ├── has → Parameter
                  └── checked by → ValidationRule

ValidationRule
 └── produces → ValidationResult

ValidationResult
 ├── relates to → Element
 ├── relates to → Parameter
 └── has status → ResultStatus

Or in a slightly more visual form:

Project
  |
  | 1..*
  v
Element -------- 1..* -------- Parameter
  |
  | *..1
  v
Category

ValidationRule
  |
  | applies to
  v
Element / Parameter
  |
  | produces
  v
ValidationResult

What this diagram gives you: it clarifies which entities the validation logic actually rests on and how the data relates to each other.

A state diagram becomes useful when the life of an object over time matters. Which states it can be in, which transitions are allowed or forbidden, what actually moves it from one status to another. It works especially well for requests, orders, documents, tickets—anything with status-driven logic.

State diagram — when you need to show an object’s lifecycle

For the Revit add-in example, it makes sense to show not just a “check result,” but—for instance—the lifecycle of a validation issue.

[New]
  ↓
[Detected]
  ├──→ [Reviewed]
  │         ├──→ [Fixed]
  │         └──→ [Ignored]
  │
  └──→ [Fixed]

Or with a bit more detail:

[New]
  ↓
[Detected]
  ↓
[Reviewed]
  ├──→ [Fixed]
  ├──→ [Ignored]
  └──→ [Recheck Required]
                ↓
             [Detected]

What this diagram gives you: it pins down which states an error or check result can be in, which transitions are allowed, and where the “detected → reviewed → fixed / ignored / sent back for recheck” logic actually lives.

That is especially useful if the add-in does not only show a flat error list, but keeps a history of checks, lets people confirm exceptions, or works with comments across several stages.

C4 helps when you need to explain the system at an architectural level. What the system actually is, what it interacts with, what external links it has, which containers and components it is made of. It is a good way to show structure without sliding into overly heavy UML detail.

C4 — when you need to show the system at an architectural level

C4 is useful when you should not spell out every call in detail, but explain what the solution is made of and where its boundaries run.

For the add-in example, you can start with a context diagram:

[User / BIM Specialist]
        |
        | uses
        v
[Revit Validation Plugin]
        |
        | works inside
        v
[Autodesk Revit]

[Revit Validation Plugin]
        |
        | reads model data from
        v
[Revit Model]

[Revit Validation Plugin]
        |
        | loads rules from
        v
[Rules Storage / Config File / External API]

If you zoom in to the container level, you can show something like this:

[User]
   |
   v
[Revit Plugin UI]
   |
   v
[Validation Engine]
   | \
   |  \
   |   --> [Rules Provider]
   |
   ---> [Revit API Adapter]

[Rules Provider]
   |
   --> [Local Config / External API]

[Validation Engine]
   |
   --> [Validation Results]

What this diagram gives you: it helps explain the solution architecture—which major parts exist, how they connect, where the add-in ends, and where external dependencies begin.

If BPMN answers “how does the process flow?” and a sequence diagram answers “who interacts with whom?”, then C4 answers: “what is this solution actually made of?”

A use case diagram is useful at the start, when you need to quickly outline who interacts with the system at all and which scenarios exist. It is not the deepest diagram, but it helps fix the boundary: which actors exist, what they want to do, where the product ends.

Use case diagram — when you need to show who uses the system and why

Use cases work well at the very top level. They do not explain implementation details, but they help pin down which roles interact with the system and for which scenarios.

For the Revit add-in example, it might look like this:

                [BIM Specialist]
                      |
      -----------------------------------------
      |                   |                   |
      v                   v                   v
[Run validation] [View validation issues] [Re-run validation]

                [BIM Coordinator]
                      |
      -----------------------------------------
      |                   |                   |
      v                   v                   v
 [Configure rules] [Review report] [Approve exception]

                [System Administrator]
                      |
      --------------------------------
      |                              |
      v                              v
[Load configuration]      [Update validation rules]

Or in a more compact form:

Actor: BIM Specialist
- Run validation
- View validation results
- Re-run validation

Actor: BIM Coordinator
- Configure validation rules
- Review issues
- Approve exceptions

Actor: Administrator
- Maintain rule source
- Update plugin configuration

What this diagram gives you: a quick view of the system boundary—who the users are, which key scenarios the system supports, and where its responsibility ends.

Use cases are especially valuable early in a project, when you need to agree not on internal logic, but on who the system is for and what it must let people do.

You can see this clearly in a concrete example—say, a Revit add-in that checks whether model parameters are filled in before documentation is issued.

At first the task may look simple: “add a check button.” But as soon as you unpack it properly, it becomes obvious that one diagram will not be enough.

If you need to understand how the user actually works with the check, it helps to draw the process. For example: the user starts the check, the add-in collects elements of the relevant categories, validates parameters, builds an error list, shows the result, and the user either fixes the model manually or runs the check again. BPMN—or at least an activity-style view—fits here, because what matters is the flow of actions.

If you need to understand how the solution interacts technically, you need a different lens. Suppose we have a Revit add-in, a validation rules module, local configuration, and perhaps an external service with corporate standards. Then a sequence diagram is more useful: the user clicks a button, the add-in calls the analysis module, it reads element parameters, then talks to configuration or an API, returns errors, and the UI shows the result. That is no longer a business process in the narrow sense—it is a sequence of technical interactions.

If you need to untangle which data participates in the check, an ER diagram—or at least a simplified entity model—is easier to read. For example: there is a Project, an Element, a Category, a Parameter, a ValidationRule, a ValidationResult. Here it is not about who clicks what, but how the objects that carry the validation logic relate to each other.

If you need to capture how an error or a check result lives over time, you may also need a state diagram. For example: New, Detected, Reviewed, Fixed, Ignored. Especially if the add-in keeps a history of checks, supports re-validation, or manual approval of exceptions.

And if you then need to explain all of this to the team as a whole, a high-level C4 view helps: where the Revit add-in sits, whether there is an external API, where rule configuration lives, whether there is a database for results, and how it all connects.

So even for a seemingly local task like a parameter-check add-in for Revit, several layers appear quickly: process, interaction, data, states, solution boundaries. Each diagram surfaces only one of them.

Taken together, this makes it clear why one diagram is almost never enough. Not because the analyst missed something, but because a living system is always layered. It has processes, data, roles, states, interactions, technical boundaries. Each diagram surfaces only one layer.

The trouble starts when people try to pack everything into a single picture. The result is something halfway between a process, an architecture, and a data diagram—arrows everywhere, boxes labeled too vaguely, and you can tell what the author meant only if they stand next to you and narrate. Such a diagram creates an illusion of understanding, but rarely helps in real work.

A good diagram almost always cuts something away.

It does not have to explain the whole system. It has to be useful for a specific conversation. Sometimes that is enough.

So in an analyst’s work, what matters is not only the ability to draw, but the ability to choose the right viewing angle. Not “which notation do I know,” but “what exactly do I want to make visible.” Process? Data? Interaction? States? Architectural boundaries?

Only after that does a sensible question about tooling even appear.

In practice, most analysts need only a handful of tools. For quick, general-purpose diagrams, draw.io or diagrams.net are common. For collaborative drafts and discussions—Miro. If you want diagrams closer to documentation and code, Mermaid or PlantUML are worth a look. For BPMN there are dedicated tools such as Camunda Modeler. For C4—Structurizr. But to me, the tool is secondary here. If it is unclear what you want to show, no editor will save you.

Perhaps that is the main point of diagrams in systems analysis.

They are not needed because “that is how it is done.” Not because a good analyst must draw something. They are needed because a system is almost always more complex than its text description. At some point, without a visual layer, the discussion starts to fragment: everyone holds a different version of the process, the logic, and the boundaries in their head.

A good diagram reduces that drift.