How to make a diagram by picking the type first

If you want to know how to make a diagram, pick the type before you write a box: a flowchart for decisions, a sequence diagram for calls, an ER diagram for the data. Skipping that pick is how you spend an hour on a picture that answers the wrong question.

I’m going to use one story, a shopper placing an order, and show the two pictures I actually argue about, plus the data picture you draw when the argument was never about steps. Diagrams as code means the picture is a file. The file has a first line. That first line is the decision. Everything after it is details you can fix.

The question decides the first line

I ask one rude question before anyone opens a tool. “What would make this diagram wrong?” If the answer is “the No path is missing,” I want a flowchart. If the answer is “we never showed the service answering,” I want a sequence diagram. If the answer is “the order line doesn’t know which product it is,” I want an ER diagram. If the answer is “it should look cooler,” I close the laptop. Cooler is not a defect I can fix with a keyword.

People skip this because the story feels like one story. It is one story. It is not one picture. “Shopper places an order” contains a policy (what we do when the card fails), a conversation (who calls the card service), and a schema (what we store). Draw all three in one chart and you get a flowchart with little database cylinders hanging off the side and a teammate who thinks the cylinder is a step. It isn’t. It’s a noun wearing a shape.

Mermaid is the language I use for that file. The what Mermaid is page is the longer definition, including what the tool will not pretend to be. This page assumes you’ll accept text as the source of truth. If you need the sales version of that idea, the Mermaid diagram explainer is the companion. I care more about the first line of the file than about the definition.

A flowchart when the policy has a fork

Here’s the order as a policy. The shopper submits. We check stock. We charge. We either confirm or we don’t. The interesting part is the two failures, because a chart that only shows the happy path is a poster.

flowchart TD
    submit[Submit order] --> stock{"In stock?"}
    stock -->|No| sorry[Tell the shopper]
    stock -->|Yes| charge[Charge card]
    charge --> paid{"Charge ok?"}
    paid -->|No| sorry
    paid -->|Yes| confirm[Confirm order]

Read the forks. Out of stock and a failed charge land on the same message, and that may be too crude for your shop. I combined them on purpose so you can see the smell. If those messages must differ (“we’ll email you” versus “try another card”), they are two nodes. I used one because the ticket said “tell the shopper” and I refuse to invent a copy deck inside a diagram. That’s an opinion. The alternative is a chart full of sentences nobody will translate.

sorry is a rectangle, not a diamond. The decision already happened. A second diamond that says “did we tell them?” is a flowchart of your anxiety. Either the step exists or you don’t draw it.

Direction is top down because the questions stack. I don’t put this left to right to fill a slide. A wide chart of two diamonds becomes a hallway, and the No edges look like optional extras. They aren’t optional. They’re the chart.

The five-minute flowchart cut is the practical pass if your source material is a messy paragraph. Use it when you already know you want a flowchart and the paragraph is fighting you. Don’t use it to avoid choosing. If the paragraph is mostly “then the API returns,” you wanted the next section, not a pile of rectangles.

A sequence diagram when the argument is about the reply

Same order. Different defect. Last quarter we had a bug where the page showed “confirmed” before the charge service had answered, because the chart everyone trusted was the flowchart above. The flowchart says “charge, then confirm.” It does not say that the browser must wait for the API, and the API must wait for the card service. A hurried reader treats the boxes as a list of components. A sequence diagram makes the wait ugly, which is what I want.

sequenceDiagram
    participant Web as Web
    participant API as API
    participant Card as Card
    Web->>API: Place order
    API->>Card: Charge
    alt approved
        Card-->>API: OK
        API-->>Web: Confirmed
    else declined
        Card-->>API: No
        API-->>Web: Failed
    end

Web does not talk to Card. That was the whole argument, and the flowchart couldn’t settle it without a note in the margin. The dotted arrows are replies. If you draw every arrow solid, the reply looks like a new request and someone will implement a second call. I did that once, years ago, on a refund path. The solid arrow home got read as “call the client,” which doesn’t even make sense, and we still built a webhook nobody asked for. The line style would have stopped it. The line style was my job.

alt is the charge diamond from the flowchart, written as a branch on the reply. Notice what disappeared: stock. I left stock out because this picture is the charge conversation. Putting stock here as a fourth participant is how sequence diagrams become flowcharts with extra furniture. If stock is a call to another service, add it as its own diagram or add one message. Don’t add it as a comment and hope.

This is also why I won’t start a beginner in a blank file with ten participants. Three lifelines, one happy reply, one sad reply. If you need loops, read them after this renders. A loop on the first day becomes an infinite retry with no backoff, drawn as if that were fine.

An ER diagram when the nouns are the fight

Sometimes nobody is confused about the steps. They’re confused about what an order contains. A line that doesn’t point at a product will get a product name copied onto it, and six months later the product is renamed and the old orders lie. That’s not a flowchart problem. Drawing it as a flowchart (“create product, then create line”) makes the copy smell like a step you can reorder.

I still write the ER in Mermaid, because the file should live next to the other two. One order has one or more lines. A product shows up on zero or more lines. The line is its own thing, with a quantity, so you don’t pretend a product “is” the order.

erDiagram
    ORDER ||--|{ LINE : contains
    PRODUCT ||--o{ LINE : "listed on"
    ORDER {
        string id PK
        string status
    }
    LINE {
        int qty
    }
    PRODUCT {
        string sku PK
        string name
    }

The crow’s feet are the part beginners skip, and then they argue about boxes. ||--|{ says an order contains at least one line. If your shop allows an empty draft order, that relationship is a lie and you should change it to zero-or-more before someone adds a database constraint from the picture. I have watched a migration get written off a diagram that said “at least one” while the code allowed drafts. The migration failed in production on the empty carts. The diagram was “just a sketch.” The migration didn’t know that.

I don’t put the charge service in this diagram. The card service is not a table. If you need both the schema and the call, you need both files. One file that tries to be both is how CARD_SERVICE becomes a fake entity with a field called does_charge. I’ve seen the fake entity. It had three columns and no rows, and it still made the onboarding doc look official.

Write the file in the order a reviewer reads it

Once the type is chosen, the writing order is boring, and boring is what you want.

First the keyword: flowchart TD, or sequenceDiagram, or erDiagram. If you can’t say that keyword out loud, you’re not ready to add boxes.

Second, the cast. Nodes, participants, or entities. Names a teammate already uses. “Backend” is not a name if the repo says orders-api. I lost a review because the diagram said Backend and the reader didn’t know which of four services that was. They guessed. They guessed wrong. Use the repo’s word.

Third, the relationships, and only the ones that change the meaning. Every arrow is a claim. “Submit goes to stock check” is a claim. “Web calls API” is a claim. “Order contains lines” is a claim. A decorative arrow is a claim you didn’t mean. Delete it.

Fourth, the failure you are tempted to skip. The No path, the declined branch, the optional relationship. A beginner diagram without a failure is a brochure. Brochures don’t belong in the repo.

The diagram index is the shelf of types when flowchart, sequence, and ER aren’t the question you have. A state diagram, a journey, a mind map: they exist, and they answer different rude questions. I don’t tour them here. If you open the index before you’ve written the first line, you’ll collect types the way some people collect notebooks. Pick one.

The cheat sheet is what I keep open for the punctuation, not for the theory. Quotes around a label with parentheses. No node id called end. A reply arrow that is dotted. Those are the typos that blank the preview and convince a beginner that diagrams as code are “finicky.” The finicky part is five characters. The hard part was choosing the type.

Generate a draft only after the type is a word you typed

The AI diagram generator will pick a type for you if your sentence says “diagram.” That’s the beginner failure with extra steps. You spend a free AI use, you get a sequence diagram of a policy, and you try to read lifelines as if they were decisions. They aren’t. Put the keyword in the prompt. “Flowchart, top down” or “sequence diagram, participants Web, API, Card.” The prompting lesson is the page for how to write that sentence so the draft is valid and not just pretty. I’m not repeating the bad-prompt autopsy here. I am saying the type comes first even when a model is typing.

Five free AI uses total is the budget. Don’t spend one on “how to make a diagram of our thing” with no type. Spend it after you’ve said flowchart or sequence or ER out loud and written the cast in the prompt. If you already know the cast, type it yourself. Generation is for the blank page, not for renaming sorry to out of stock.

A model will also mix types in one file if you ramble. You’ll get a flowchart with a note that says “see sequence.” Notes aren’t links the renderer checks. Split the files. Name them order-policy.md and order-charge.md or whatever your repo already does. Future you should not have to guess which picture answers which review comment.

The mistakes that make beginners think they’re bad at this

Drawing the UI. A rectangle per screen, with the buttons written inside, is a wireframe done poorly. The order flowchart above has no “cart page.” The cart page is where the shopper clicks. The diagram starts at submit because that’s the policy. If you need the screens, you still probably need a flowchart of decisions, not a gallery of frames. I keep saying this because every new hire draws the screens first. The screens are what they can see. The bug is in the branch they didn’t draw.

Using one diagram as the team’s memory for everything. The flowchart becomes a dumping ground for “also fraud,” “also email,” “also the warehouse in Ohio.” Soon it doesn’t render on a laptop without sideways scroll, and people stop opening it. Split by the rude question. Two small charts get read. One mural gets linked and ignored. I have the ignored mural in an old repo. It’s still wrong, and it’s still linked from the README, which is worse than deleting it.

Trusting the layout as meaning. Mermaid places flowchart nodes where they fit. If two boxes are close, that does not mean they happen together. Sequence diagrams are stricter about time, top to bottom. ER diagrams are stricter about nouns. If you need a box to stay in a row because the row means “this tier,” you wanted a block diagram, not a flowchart. Don’t fight the flowchart with blank nodes to fake a grid. I’ve tried. The next edit undoes it.

Copying a chart from a blog and changing the title. The structure is the claim. If you keep my stock diamond and your shop doesn’t check stock until after payment, you documented my shop. The drawing overview is about making the picture, not about donating your policy to whatever example was handy.

Leave the file where the argument will happen again

A diagram that lives in a slide is a fossil by Thursday. The file belongs next to the code or the doc that will change when the policy changes. Update the No path in the same pull request as the behavior. If that’s annoying, the diagram is too big. Shrink it until the diff is a couple of lines you can read in review.

Beginners ask which tool. Any editor that shows the text and the picture will do for the first hour. I use ours because the preview is right there and I don’t have to install a preview plugin to find a missing quote. You can make the order flowchart, then the sequence, then decide the ER is a problem for another day. That order matches the argument: policy, then calls, then nouns. Don’t start with the ER because it feels more “technical.” Start with the picture whose wrongness would hurt this week.

Open the editor, type flowchart TD or sequenceDiagram on line one, and add the failure before you add a third happy step. The type is the diagram. The boxes are just you keeping the type honest.