You open a design doc from last March. The prose says the checkout service calls the ledger over gRPC. The diagram below it, a PNG someone exported from Lucidchart, shows a queue sitting between them. One of those is true. Nothing in the document tells you which one, and the person who drew the picture left in November.

You will trust the picture. So will the engineer who joins your team in October. A reader scans a diagram in two seconds and reads three paragraphs in ninety, so you take your mental model from the boxes and skim the prose for confirmation. That would be fine if the two stayed in sync. They don't, because your team edits them under different rules.

Your team reviews the paragraph and skips the picture

When an engineer changes how checkout talks to the ledger, they open a PR, edit the paragraph, and someone comments on the wording. That loop takes four minutes. Fixing the diagram means opening a different app, hunting for who owns the board, discovering the owner offboarded, requesting access, editing, exporting a PNG at the right scale, and dropping it back in the repo. That loop takes forty minutes and produces a commit that reads Binary files a/docs/checkout.png and b/docs/checkout.png differ. No reviewer can argue with that line. So the engineer skips it, and the doc now carries a claim nobody approved.

Six months of that and the diagram describes a system you decommissioned. New hires still read it first.

Write the diagram as text in the same file

Put the source of the picture in the markdown, under the paragraph it explains:

sequenceDiagram
    participant C as Checkout
    participant P as Payments
    participant L as Ledger
    C->>P: authorize(order_id, amount)
    P->>L: reserve(amount)
    L-->>P: reservation_id
    P-->>C: authorized

Seven lines of plain text sit in the file, fenced with mermaid instead of ts or sql. Each ->> line declares a call, each -->> line declares a return, and the renderer turns them into what you see above: three labeled lifelines across the top, time running down the page, solid arrows for requests and dashed arrows for responses. A reader gets the same boxes and arrows they would have gotten from Lucidchart. You collect on the trade the day someone moves the reservation behind a queue. They edit one line, the diff reads

-    P->>L: reserve(amount)
+    P->>Q: enqueue(reserve, amount)

and a reviewer who knows the system reads that in a second and says the ledger still needs a synchronous path for refunds. Now the picture went through the same gate as the paragraph, in the same PR, argued over by the same two people.

Flowcharts work the same way. graph TD plus a handful of A --> B lines gives you a decision tree that someone can correct without a mouse.

The objection, and why I don't buy it

Mermaid draws worse pictures than Figma. That's true. You get no control over layout, the engine places the nodes, and if you want a box two centimeters left you can't have it. I'll take that trade. Your team stops losing Thursday afternoons to aligning rectangles, and the diff stays about the graph instead of about coordinates. Save the drawing tool for the system map you present at an offsite, where the layout carries meaning and one person owns it. For the doc four engineers read on a Tuesday before they touch the code, boxes and arrows do the job.

Engineers raise a second objection: markdown diagrams look cheap in a doc you send to a partner team. Render them as vector SVG in a light card and they look like diagrams. The complaint traces back to a screenshot of a screenshot, a rendering problem you fix once.

Two rules worth enforcing

Keep the diagram inline, under the paragraph that explains it, never in an appendix at the bottom. Distance lets the two drift. A reader who has to scroll to check the picture against the words will not scroll.

When the prose and the diagram disagree in review, block the PR. Treat it the way you treat a test that fails. Someone has to decide which one is right before the doc ships, and that decision costs five minutes now instead of an incident later.

Where this tool fits

I built markdownwithdiagrams.com for the part that stays awkward: a partner team or a compliance reviewer asks for the doc as a file rather than a repo link. You paste the markdown into the editor, the preview on the right renders the mermaid blocks as vector SVG, and the export gives you an A4 PDF with 1in margins where the text stays selectable and the diagrams stay vector at any zoom. No account, no server storage. The markdown file in your repo remains the source, and the PDF is a copy you hand to someone.

Next time you write a design doc, skip the drawing app and type the seven lines. When you turn out to be wrong about the architecture in six months, someone will fix your diagram in the same PR where they fix your sentence.