AI visual explainers need respect for the reader

AI visuals are good enough now that they create a new editorial problem.

They can make an article look explained before anything has actually been explained.

That is a real trap for technical writing. A generated diagram can add rhythm and relief, but it can also smuggle in nonsense. Arrows point nowhere. Layer names sound plausible and still do not match the architecture. Screenshots invent UI states that the product never has. A “neural network” turns into blue glowing spaghetti because that is what the model thinks the topic looks like. A security diagram puts a lock around the least important part of the system because locks read as security.

The reader pays for that with attention.

start from the question

Before I add a visual, I want to know what question it answers.

Can the reader see the order of operations faster? Can they compare two states? Can they spot the boundary where data crosses from one place to another? Can they understand a shape that would take too many words to explain? Can they manipulate a value and watch the system change?

If the answer is no, the visual is probably decoration.

Decoration is not always evil. A personal site can have style. A post can have mood. But an explainer image has a job. If it sits inside a technical article, it should carry technical weight. For tool calling, that might be a sequence diagram. For embeddings, it might be a small scatterplot. For backpropagation, it might be a table of intermediate values before it becomes a glowing brain.

The simplest test is still the best one: remove the image and ask what got harder to understand.

If nothing got harder, the image was borrowing credibility from the article.

what generated images need to survive

AI image generation is seductive because it makes the blank space disappear. That is also the trap.

The model does not know whether the architecture makes sense unless the prompt and review force it to. It may draw a database on both sides of the same boundary. It may label a browser as a server. It may use bidirectional arrows because they look complex. It may create interface text that almost says something.

Generated visuals need the same editorial treatment as generated prose. Maybe more.

When I review one, I check boring things first:

• are the labels real nouns from the article?
• does every arrow have a direction that means something?
• does the image imply a component the text never explains?
• are there invented metrics, product names, or claims?
• could a reader reproduce the idea from the visual alone?
• is the visual still accurate at small size?
• does it work without color?

The last two matter more than people want to admit. A diagram that only works as a full-width hero is often a poster, not an explainer. If the text gets tiny, the contrast is weak, or the meaning depends on three shades of blue, the reader gets a pretty blur.

I would rather use a plain table than a beautiful diagram that lies.

screenshots should prove something

Screenshots fail differently.

They feel concrete because they show a real or plausible interface. But a screenshot can still dodge the point. It can show the happy path while the article is about error recovery. It can crop away the part where the decision happens. It can show fake data that makes every layout problem disappear.

If a screenshot appears in a technical post, it should make the claim more accountable.

Show the awkward state. Show the empty result. Show the approval prompt with the actual resource name. Show the trace view after a tool call fails. Show the long label wrapping. Show the diff. Show the queue with a poisoned job sitting in the dead-letter list.

This is where AI-generated UI images are especially risky. They invent a better product than the one being discussed. The chart is clean. The dashboard is full. The data is conveniently shaped. The dangerous state is absent. The visual says, “Imagine this is solved,” while the article is supposed to explain the unsolved part.

That is not respect for the reader. It is set dressing.

uncertainty should stay visible

A lot of system diagrams are too confident.

They draw crisp boxes around things that are actually fuzzy. They make feedback loops look linear. They make retries look like ordinary arrows. They hide the queue, the cache, the human approval step, the timeout, the rate limit, or the piece of state nobody owns.

AI makes this worse because generated diagrams often prefer symmetry. Symmetry looks finished. Real systems are usually lumpier.

If the article is about an early idea, the diagram should look like an early idea. If a boundary is uncertain, mark it as uncertain. If a component might disappear in the simpler version, say that. If the hardest part is the handoff between two boxes, do not hide it behind a thick arrow.

Technical visuals do not have to pretend the author knows more than they know.

Some of the best diagrams are ugly because they make the problem honest. A rough state chart with one suspicious transition is more useful than a polished architecture render that makes every failure path vanish.

interaction is better when the topic moves

When a topic involves motion, state, or parameter changes, a static generated image is often the weakest option.

For neural networks, let the reader change a weight. For ranking, let them move a score and watch the order change. For caching, let them invalidate a key. For a queue, let a worker fail and watch the retry count move. For a shader, let the slider change the function.

The point is not to make the post fancy. The point is to let the reader test their mental model.

An interactive explainer has to be disciplined too. It needs a small number of controls, stable labels, and a visible relationship between input and output. If the reader can change five knobs and nothing obvious happens, the interactivity is theater.

This is the version that earns its space:

chunk size: 200 tokens
overlap: 40 tokens
result: 18 chunks
retrieval risk: section boundary split across chunks 7 and 8

That teaches more than a generated illustration of documents flying into a vector database.

the reader’s job should get easier

The reader is already doing work. They are holding the argument in their head, mapping terms to concepts, and deciding whether the article is worth trusting.

A good visual reduces that load. It makes a relationship visible faster than prose alone would. It gives the reader a handle on the system. It turns a hidden step into something they can inspect.

A bad visual does the opposite while pretending to help.

That is why I keep coming back to respect. AI made visuals cheaper, but the reader’s attention did not get cheaper. If anything, it got more expensive because every article now has the option to decorate itself into a fog machine.

Use the visual when it teaches. Cut it when it only flatters the page.