From Requirements Text to a Mermaid Flow in 5 Minutes
Turn a short written requirement into a Mermaid flowchart, one sentence at a time. Keep each sentence as a comment above its code so reviewers can trace every line back to the requirement. A returns process for an online shop.
Step by step
Text to flow
- Requirements to flow. You leave a workshop with a paragraph of requirements and need a process map fast. Read the paragraph one sentence at a time and turn each sentence into 1 or 2 lines of Mermaid. The example is a returns process for an online shop.
The requirement
- Read it first. The requirement: A return request arrives. If it's more than 30 days old, refuse it. Otherwise the warehouse inspects the item. Damaged items are refused too. Good items get a refund.
Sentence by sentence
- Diagram type. Clear the editor and type flowchart TD. TD means top down, so the flow is drawn from top to bottom.
flowchart TD - Sentence as comment. Type sentence 1 as a comment first: %% A return request arrives. 2 percent signs start a comment, and Mermaid doesn't draw it. Under it, A([Return requested]) --> B{Under 30 days?} draws a rounded start shape with an arrow to a decision diamond. Render it. The comment stays in the code, but only the 2 shapes and the arrow appear in the drawing.
%% A return request arrives A([Return requested]) --> B{Under 30 days?} - One sentence, one line. Sentence 2: if it's too old, refuse it. Add the comment %% Too old: refuse it, then B -->|No| R([Return refused]). The No path from the decision now ends at Return refused. Its short ID is R, because a later rule needs it again. Sentence 3: otherwise, the warehouse inspects the item. B -->|Yes| C[Inspect item] adds an inspection box on the Yes path, and C --> D{Damaged?} leads to the second decision. Render again. 3 sentences have become 3 small pieces of the flow.
%% Too old: refuse it B -->|No| R([Return refused])%% Else the warehouse inspects it B -->|Yes| C[Inspect item] C --> D{Damaged?} - Reuse an ID. Sentence 4: damaged items are refused too. Don't draw a second Return refused shape. Write D -->|Yes| R, which points the Yes path at the R you already have.
%% Damaged items are refused too D -->|Yes| R - One sentence, one line. Sentence 5: good items get a refund. D -->|No| E[Refund customer] adds the refund step, and E --> F([Return closed]) ends the flow. Render the finished flow. 5 sentences have become 1 complete flow with 2 decisions, and every path reaches an end shape.
%% Good items get a refund D -->|No| E[Refund customer] E --> F([Return closed]) - Reuse an ID. In the drawing, both refusal paths meet at the one Return refused shape, because they share the ID R.
Check it
- Trace it back. Now check it. Read each comment, then the code under it. If a sentence has no code under it, you missed a rule. If some code has no sentence above it, ask the stakeholder where it came from.
Recap
- The rules. The method: take the requirement one sentence at a time. Write each sentence as a comment and code it underneath. Reuse IDs where paths meet, then trace every line back to its sentence.
Common mistakes
- Drawing a second refused shape. If you write a new shape like R2([Return refused]), you get 2 identical end shapes, and the map no longer shows that both paths end the same way. Point the second arrow at the ID you already have instead: D -->|Yes| R.
- Using one ID for 2 different steps. Mermaid treats every use of an ID as the same box. If you type C for both the inspection and the refund, they merge into 1 box. Give each new step its own ID.
- Putting a comment on the same line as code. Mermaid expects %% comments on their own line. Put each sentence on the line above its code, as in the lesson.
- A decision worded differently from the rule. The rule refuses returns that are more than 30 days old, but Under 30 days? also sends a return on day 30 down the No path. Word the diamond like the rule, for example 30 days or less?, or check that edge case with the stakeholder.
When a business analyst uses this
After a requirements workshop, paste the agreed rules into the Mermaid file as %% comments and code each one underneath. At the walkthrough before sign-off, stakeholders can check every box and arrow against the sentence it came from. Any sentence with no code under it shows a missed rule.
Questions people ask
How do you write a comment in Mermaid?
Start the line with %%. Mermaid skips that line when it draws, so it's a safe place to keep the requirement text. Put each comment on its own line.
What does flowchart TD mean in Mermaid?
It starts a flowchart that is drawn top down. TB means the same thing, and LR draws the flow from left to right.
How do you make 2 arrows point to the same box in Mermaid?
Give the box a short ID the first time you draw it, like R([Return refused]). After that, use only the ID, like D -->|Yes| R, and the arrow joins the existing box.
