Keep the diagram next to the text that explains it
Design docs and their diagrams drift apart within months, so write the picture as Mermaid in the same markdown file and let code review catch both.
Read it →Writing
Why diagrams belong in the same file as the prose, and how to hand someone a document they can read.
Stop screenshotting your Mermaid diagrams
A screenshot of your Mermaid diagram blurs at print resolution and hides the text from search. Export the markdown to vector PDF instead.
Read it →The design doc people actually read
Most design docs fail because the author writes for the author. Structure yours for a reviewer who reads it once, in a meeting, on a printout.
Read it →