DEV Community

weiwuji
weiwuji

Posted on

In Diagrams, Precision > Pretty: Why Technical Articles Use Code-Generated Images

#ai

The Pain: When adding diagrams to technical articles, there are two classic pitfalls — either you paste dense screenshots that readers can't make out, or you have AI draw a lovely illustration that nobody can tell what it's about.
What You'll Learn: An understanding of the principle "precision > pretty" in diagrams, and why code-generated images are the best choice for technical articles — precise as the baseline, and good-looking on top of it.

0. The essence of diagrams: making the point clear

Diagrams in technical articles aren't decoration — they're information carriers.

A good technical diagram: one glance and the reader grasps "how this flow works," "where this comparison differs," "how many layers this architecture has."

A bad technical diagram: beautiful, but the reader leaves more confused than before.

1. Two ways to make diagrams

Way A: AI text-to-image (let the model draw) 

Input: a description → Output: an AI-generated image
Pros: great visual texture (3D materials/magazine feel)
Risks: ⚠️ Text can be wrong/blurry/cropped (AI-drawn text is uncontrollable)
      ⚠️ Data can be mangled (chart semantics redrawn)
Enter fullscreen mode Exit fullscreen mode

Way B: Code-generated images (SVG rendering) 

Input: structured data → code generates SVG → renders to PNG
Pros: ✅ Text 100% precise (code-rendered)
     ✅ Data 100% precise (values fully controlled)
     ✅ Free + fully reproducible
Risks: ⚠️ Visual quality requires design work (template-driven)
Enter fullscreen mode Exit fullscreen mode

Comparing the two approaches

2. Why "precision > pretty"

What's special about technical articles 

General article diagrams: pretty is enough (emotion/atmosphere)
Technical article diagrams: precision is the baseline (information/logic)

Wrong process label → readers follow it and get it wrong
Wrong data on a chart → readers believe it, and everything built on it is wrong
Enter fullscreen mode Exit fullscreen mode

One wrong diagram in a technical article can destroy the trust of the entire piece.

An example

Say you're diagramming an "agent workflow":

  • Text-to-image: the AI might render "User Input" as "System Input," the label blurs, and readers have to guess
  • Code-generated: labels like "User Input," "AI Execution," "Result Check" are pixel-perfect

Precision vs. blur

3. My approach: precision first, aesthetics second

My diagram system: code-generated (SVG) as the backbone, borrowing the visual texture of AI imagery.

SVG code generation (guarantees precision)
  + material-style 3D look (borrows the pretty)
  + short labels (2-5 characters, only labels inside the image)
  + QA checks (labels legible / data correct / no cropping)
  = diagrams that are both precise and good-looking
Enter fullscreen mode Exit fullscreen mode

Concretely:

  1. Precision: SVG code rendering — text/data 100% under control
  2. Aesthetics: material-style visuals (soft shadows / IKB blue / Swiss layout) — learn the "texture" from AI text-to-image style, skip its "uncontrollability"
  3. Short labels: in-image text ≤ 6 characters — "Result Check," not "Check the Execution Result"
  4. QA: after generation, check labels / data / cropping

My diagram approach

4. Why I don't use AI text-to-image for in-body diagrams

To be clear: AI text-to-image isn't bad — it's great for covers, banners, and decorative illustrations.

My choice is division of labor by purpose:

Purpose Approach Reason
In-body concept/flow diagrams Code-generated (SVG) Text/data must be precise
Covers/Banners AI text-to-image Decorative, no text requirements
Real screenshots/command output Actual captures The iron rule of authenticity

5. Where you are now

Right now, you've stopped paying for "a pretty image" — you've started paying for "an image that explains itself."

You're becoming the kind of — strict reader who looks at a diagram and asks "does it explain the point?" before "does it look good?"

Remember: precision > pretty. A technical article's diagrams are information carriers, not decorations — but on a precise foundation, they can absolutely be prettier.

🏷️ Substance: SVG diagrams, code generation, AI text-to-image, short labels
💼 Value: accurate information, trust-building, visual texture, diagram efficiency
🧠 Cognition: Precision > pretty in diagrams — a diagram is an information carrier, not a decoration, but on a precise foundation it can be prettier

📌 About the author
About the author: Wu Ji (无记) — AI / Agent / digital transformation practitioner. I only write about things I've actually built and run — no concepts without practice. Follow along, and let's turn cognition into income.

📖 Further Reading

Top comments (0)