Writing on diagrams
Practical notes on diagrams, docs, and developer ergonomics — published weekly.
Mermaid vs PlantUML in 2026: Which to Pick for Engineering Docs
Mermaid and PlantUML solve the same problem with different trade-offs. Here's a 2026 comparison on syntax, layout quality, diagram coverage, and ecosystem — with a decision rule at the end.
Embed Mermaid in Notion: The 4 Working Approaches in 2026
Notion's native Mermaid block is fine for quick notes — but breaks the moment you want a theme, live updates, or a clean export. Here are the four embedding paths that actually work in 2026.
Why Your GitHub README Diagrams Look Amateur (and the 4 Fixes That Take 10 Minutes)
Most README diagrams suffer from the same four defaults. Here's how to fix all of them in under ten minutes — without redrawing anything.
How to Render Mermaid Diagrams as SVG (and Stop Looking Like Every Other README)
A practical guide to rendering Mermaid as SVG — from the official CLI to custom themes, font fixes, dark mode, and the fastest path when you don't want to tune anything.