Make a flow chart in about five minutes

You can make a flow chart in about five minutes if you start from the messy process you already have and only then write Mermaid. The first picture will be too long. That’s the point of the first picture. You’ll cut it before anyone else has to follow it.

I’m using a password reset, because everyone has one and most of them are described as a paragraph in a ticket. The paragraph is true and unreadable. The chart is how you find the sentence that was doing too much work.

Start from the messy paragraph, not from a blank symbol

Here’s the process as a teammate actually wrote it in Slack. I didn’t clean it up.

“User forgets password, clicks the link on the login page, we email them, they open the email, if the token is old we should probably tell them to try again, also rate limit so people can’t spam, and if the token is fine they type a new password twice, and we should update the wiki, and maybe ping security if it looks weird, then they’re logged in I think, or do they have to log in again?”

That paragraph contains a real flow and three things that are not the flow. Updating the wiki is a chore for us, not a step for the user. Pinging security is an incident path, not the happy reset. “I think” is the author admitting the end state isn’t decided. If you draw all of it, you will defend the wiki box in review, and you will lose.

I copy the paragraph into a note and underline only the user-visible steps and the questions. Forgot password. Request the email. Token still good? Set a new password. Then what. The rate limit matters, but it’s a gate on the request, not a separate product. I’ll put it on the request step as a decision, or I’ll leave it out of the first chart and say so. Leaving it out on purpose is better than burying it.

The symbol guide is where shapes get their own article. I’m not repeating the stencil lecture here. A diamond is a question, a rectangle is a step, and if you need the long version of that, go there after this chart exists. Meaning, as in “what is this picture for,” sits in what flowcharts mean. This page is the five-minute cut.

Mark the decisions before you draw anything

Two questions survive the paragraph. Is the token still good? And, once the password is set, do we drop the user into a session or send them back to the login form?

The second one was hiding in “I think.” I don’t let a chart hide it. I pick an answer and label it as a product choice, not as a fact of nature. For this example I’ll send them to the login form. I’ve seen teams do the opposite, create a session immediately, and then argue for a quarter about whether the reset link is a login. Both are implementable. Only one should be in the picture. If you draw both as if they’re the same path, your chart is the argument you refused to finish.

Rate limiting is a third question: are we over the limit? I’ll keep it, because the user sees an error, not a silent drop. Wiki and “ping security” go on a list called “not this chart.” I will forget them if I don’t write the list down. That’s fine. The list is allowed to exist. It doesn’t get a box.

A worked login template is a decent neighbor if your reset is really “log in, and also there’s a reset link.” Don’t paste the login chart and rename two boxes. The reset has a token. The login doesn’t. I’ve reviewed that mistake. The diamond said “password correct?” on a page where the user doesn’t have a password yet.

Turn the sentences into ids before they become an essay

I write a closed list on one line. Ids stay short so the arrows don’t rot when the label changes.

• ask: user asks for a reset
• limit: under the rate limit?
• mail: send the email
• open: user opens the link
• fresh: token still good?
• again: ask for a new link
• choose: user types the new password
• save: store it
• login: back to the login form

Labels can be human. Ids should not be “user types the new password twice and we check they match.” That check is either its own diamond or it’s part of choose. I fold the double-entry check into the step unless a mismatch goes somewhere surprising. A mismatch goes back to the form. That’s not surprising. A separate diamond for it is how a five-minute chart becomes a poster.

The syntax tutorial is the reference for how those ids become legal Mermaid. Use it when the preview goes blank. I’m not pasting the syntax table into this walkthrough. The mistake I care about here is drawing the wiki.

The first chart is allowed to be bad

This is the chart I get if I “just draw the paragraph” so we can see the damage. I still think you should draw it once. Looking at the junk is faster than arguing about the paragraph.

flowchart TD
    ask[User asks] --> wiki[Update the wiki]
    ask --> mail[Send email]
    ask --> sec[Ping security]
    mail --> open[Open link]
    open --> fresh{"Token good?"}
    fresh -->|Yes| choose[Type new password]
    fresh -->|No| again[Try again]
    choose --> save[Save password]
    save --> session[Create session]
    save --> form[Go to login]

Count the problems. The wiki and the security ping sit on the user’s path, so a reader thinks the reset waits on a wiki edit. It doesn’t. The token failure says “try again” and doesn’t say try what. Both terminal boxes are reachable from save, with no question between them. That’s the “I think” from Slack, preserved in ink. I have shipped this shape. Someone implemented both ends and the bug report was “sometimes I’m logged in and sometimes I’m not.” The chart had authorized both.

Also look at ask with three outgoing arrows and no labels. Unlabeled forks are how a flowchart pretends to be a mind map. If the arrows aren’t alternatives and they aren’t a sequence, they’re a confession that you didn’t know the order.

Cut until one question has two different next steps

Second pass. Wiki and security are gone. The rate limit is a real diamond because the user can hit it. The ending is one box, on purpose. I still don’t love this draft. The email step is doing two jobs in the prose around it, and “try again” is still vague. But a teammate can argue with it, which they could not do with the paragraph.

flowchart TD
    ask[Ask for reset] --> limit{"Under rate limit?"}
    limit -->|No| wait[Show the limit error]
    limit -->|Yes| mail[Send email]
    mail --> open[Open the link]
    open --> fresh{"Token still good?"}
    fresh -->|No| again[Show expired link]
    fresh -->|Yes| choose[Enter a new password]
    choose --> save[Save password]
    save --> form[Return to login]

The No on the rate limit ends. It does not loop, because a loop with no change in the picture invites a retry storm. The error tells the user to wait. If you want a loop, send them back to ask and say what they must do differently. I usually don’t. The button is still on the page. The chart doesn’t need to draw the button twice.

The expired token does not silently resend. It shows a message. Resending from a dead link is a product decision with abuse edges, and I don’t want it implied by an arrow I drew in minute four. If we add it later, it’s a new arrow from again to mail, and I’ll hate it until we name the cap.

save to form is the argument I finished. Nobody gets a session from the reset link in this version. If your product creates a session, delete form and write session instead. Don’t keep both “for clarity.” Both is the bug.

The five-minute version I’d paste in the ticket

Third pass is the one I paste. Same process, fewer words on the boxes, and the expired path tells the user the next action without inventing a resend.

flowchart TD
    ask[Request reset] --> limit{"Under the limit?"}
    limit -->|No| wait[Rate limit message]
    limit -->|Yes| mail[Email the link]
    mail --> open[Open link]
    open --> fresh{"Token fresh?"}
    fresh -->|No| again[Expired message]
    fresh -->|Yes| choose[New password]
    choose --> save[Store password]
    save --> form[Login form]

I can read this out loud in twenty seconds. Request, limit, email, open, token, password, store, login form. The two Nos are messages, not mystery retries. If a reviewer wants a session instead of the login form, they have one box to change and the diff is obvious. That is the payoff of the five minutes. The paragraph could not produce a one-box diff.

I still left the rate limit in. Some teams will call that noise and delete limit and wait. I’d rather they delete it in the open than discover we enforce it only in the API. If the chart lies by omission, say “rate limit exists, not drawn.” A caption is cheaper than a wrong diamond.

The flowchart type page has the shape catalog when you want a cylinder for the password store or a subroutine shape for “run the hasher.” I rarely need those on a reset chart. A rectangle that says “store password” is honest enough. Fancy shapes on a five-minute draft are how you spend minute twelve coloring.

Where people lose the five minutes

They open a symbol picker and hunt for the perfect “document” shape for the email. The email is a step. The shape will not save a bad order. They also try to draw the password rules: length, a number, a symbol, a sad face. Those rules are a sentence under the chart or a validation error on the form. A diamond per rule is a chart nobody will update when the policy changes from 8 characters to 12. I’ve seen the 8-character diamond survive in the wiki for two years after the code changed. The chart became a fossil with arrows.

They ask the model to “make a flow chart of password reset” and accept the first draft, which adds SMS, a backup code, and a security team. If you use the flowchart generator, paste your closed list, not the Slack paragraph. The Slack paragraph is how the wiki box returns with a nicer font.

Another loss: starting left to right because a slide is wide. This chart is a decision stack. Top down reads. Left to right turns the two diamonds into a hallway. Direction is a choice you make once, in the first line, flowchart TD. I only switch to LR when the story is a pipeline with one question at the end.

The online flowchart tool notes cover the “which kind of app” question if you’re still comparing a canvas to a text box. What the chart is for is the page about purpose, which you should read if your reset picture is actually a status report and you wanted a different diagram. Don’t force a flowchart to show a timeline. It will look like a flowchart and read like a list.

Put it where the paragraph used to be

I paste the third chart over the Slack paragraph. I keep one sentence above it: “Reset does not create a session. Expired tokens do not resend.” Those two sentences are the decisions the arrows can’t shout. The chart without them is still better than the paragraph. The chart with them is something an implementer can disagree with in a comment.

If the preview breaks, it’s almost always a label. A question mark inside a diamond is fine when the label is quoted, which is what {"Token fresh?"} is doing. An unquoted parenthesis will blank the picture. Don’t name a node end. Call it form or done and let the label say whatever the user sees.

You can make a flow chart like this in the editor from the messy paragraph you already have. Time the cut. If you’re still adding boxes at minute ten, you’re drawing the wiki.