Flowchart or written spec: which should come first?

Flowchart or written spec first? Draw first when the hard part is branching or handoffs, write first when it is rules or reasons, and keep both in step.

Written by
FlowDraw Team
Published
Reading time
5 min read
The words "Spec or flowchart first?" in large type, beside a small FlowDraw board with a User flow drawing.

Should the flowchart or the written spec come first? Teams tend to settle this by habit, when the better guide is which part of the problem is hard right now.

Quick Answer

Draw the flowchart first when the hard part is branching or handoffs, because a gap in a picture is easy to see. Write the spec first when the hard part is constraints, reasons or definitions, which a diagram can’t carry. If you’re unsure, list your open questions and see which kind you have.

Flowchart or spec: name what is hard first

Before opening anything, write down the three questions you are least sure about. They tend to fall into two kinds.

Some are flow questions. What happens when the card fails a third time? Who picks this up after support approves it? Can the customer get back to this step? Those want a drawing, because the answer is a path.

Others are definition questions. What counts as eligible for a refund? Why 30 days and not 14? What must stay true whichever path the customer takes? Those want sentences, because the answer is a rule and its reason.

Take a refund feature. If the debate is about who touches the request and in what order, draw first. If everyone agrees on the path but nobody agrees what “eligible” means, a drawing only gives the disagreement a diamond to hide in.

AspectDraw firstWrite first
The hard partBranches, retries, handoffsConstraints, reasons, definitions
Typical workCheckout retries, onboarding across three teamsRefund policy, data retention, plan limits
What it finds quicklyDead ends, missing branches, steps with no ownerContradictions, unstated assumptions, words people use differently
What it losesThe why, thresholds, what a label meansWhether every path ends, how the pieces connect

Our default, when the questions are evenly split: if the process crosses more than one team, draw first. Handoffs are where the gaps are, and people outside your team will read a picture when they won’t read four pages. Inside one team, where the argument is about rules, write first.

What you lose by drawing first

A flowchart cannot hold a reason. The box says “Hold stock for 15 minutes”, and the next person to work on it has no idea whether 15 came from a contract or a guess, so they don’t dare change it.

A diamond also hides a definition. “Eligible?” looks settled. Three people can approve that drawing, each with a different policy in mind, and you find out when the first edge case reaches support.

A diagram looks finished early, too. Neat boxes discourage argument at the stage when you still need it, so show the first draft rough and say it is rough.

What you lose by writing first

Prose runs in one line, and processes don’t. A spec can say “if the payment fails, the customer is asked to try again” and never mention the third failure, or whether the stock is still held. Sentences read as complete even when the logic is not, so a reviewer can nod all the way to the end.

Long specs also lose the readers you most need. The support lead who knows where the process really breaks will look at a picture and point at a box. They are much less likely to comment on section 4.2.

How to keep the flowchart and spec in step

Whichever came first, you will soon have both, and drift starts when both try to say the same thing.

  • Give each its own job. The spec owns definitions, reasons and non-goals. The diagram owns order and paths. Don’t retell the branches in prose or write rules into the boxes.
  • Share the names. If the diamond says “Eligible for refund?”, the spec has a heading with those exact words that defines it. A reader can move between the two without guessing.
  • Put the diagram inside the spec. A screenshot starts aging the day you paste it. A FlowDraw embed, from the “Embed” tab under “Share”, shows the board as it is when the page loads, so a spec tool that accepts iframes opens on the current drawing. If yours doesn’t, paste an exported PNG and write the date under it.
  • One owner, one sitting. The same person owns both and changes them together. If a change touches only one of them, ask why.

If you wrote first and want the drawing, turning the text into a flowchart gets you a quick first version. Paste a short spec into FlowDraw AI, which takes up to 8,000 characters, or attach it as a PDF or a Word file.

This is also a cheap way to test the spec. FlowDraw AI is told to draw what your text says and add only Start and End, so a branch your spec leaves open should stop there. Read those dead ends as your list of gaps, and check every label against the text, because a model can still misread a sentence.

If you drew first, write the spec by walking the diagram: one heading for each diamond, stating the rule and why it exists. Anything you can’t explain is a decision nobody has made yet. Once you have both, decide how much detail belongs in the flowchart, since a drawing that repeats the spec’s thresholds is usually the first to fall behind.

FAQ

Only for simple work where the path is the whole story. A flowchart shows order and branches, but it cannot explain why a rule exists, what a term means or what is out of scope. Most features need a short written spec beside the drawing, even if it is a single page.

Continue Reading

Ready to create your first diagram?

Turn your ideas, notes, or documents into a clear,
editable flowchart in seconds.

Get Started Free