---
title: "Visual Communication Beats Prose"
canonical: https://dxdev.com/blog/2026-05-10_visual-communication-beats-prose/
datePublished: 2026-05-10
---
I asked Manus to explain my own system back to me. Not because I forgot how it worked, but because I could no longer hold it in my head. Four surfaces, a dozen repos, five AI agents each with different read/write permissions into a shared vault. Every time I tried to describe it in a paragraph, I lost the thread halfway through and started over.

So I stopped writing paragraphs.

## The prompt that changed the format

The task I handed off was blunt. Pull the vault, read the batch of architecture discussions from that week, and produce two things. A static document with mermaid diagrams committed straight into the vault, and a hosted interactive site on top of it. Not a summary. Not a write-up. A map.

Manus ended up with eight diagrams. Station topology. Repo dependency graph. Agent dataflow. A five-layer conversation archive pipeline. Each one took maybe fifteen seconds to read and land completely. Compare that to the prose version of the same information, which I had tried to write three separate times and abandoned each time because by paragraph four I'd need to reference something from paragraph one and the reader (me, six weeks later) would have already lost it.

## Why prose fails for this specific thing

Prose is sequential. It forces you to pick an order for things that do not actually have an order. Which agent do I describe first, Claude Code or Manus? Doesn't matter, and any choice implies an importance ranking that isn't real. A graph doesn't have that problem. `CC --> Vault`, `Manus --> Vault`, `ChatGPT -.-> Vault` sit next to each other with no forced hierarchy, and the dashed versus solid line tells you current-versus-planned in a way that would take a whole sentence to say and still be less clear.

Tables solved a different problem. I kept getting asked, implicitly by my own confusion, "where does X live?" Where do decisions get written. Where do session manifests land. Where do blog drafts sit before they publish. That's not a narrative question, it's a lookup. A table with two columns, artifact and canonical location, answers most of those questions in the time one paragraph answers one.

## The diagram that actually got used

Not all eight diagrams were equally load-bearing. The one I keep coming back to is the content publishing pipeline: vault drafts flow to one commercial surface, a personal gateway is planned but not wired, and one surface never gets touched by content at all. Three lines.

It only exists because my brief was wrong. I fired the prompt off assuming it described the whole system, and it did not. I had forgotten to list the company site as a surface at all. Shortly after, I realized it, and the first pass confirmed it: the static document came back with seven sections, the content engine showing up as a lone node, and nothing about where a post goes once it leaves the vault. Manus was still building the hosted site, so I sent a mid-flight note asking it to add the company site as a public surface before deploying. The pipeline diagram is what came back, and it made the eighth.

I had written that same boundary out in prose before, in an earlier planning doc, and it never stuck because "never publishes" got buried in a sentence about something else. As a diagram, the box labeled "Never Published" just sits there, impossible to miss, impossible to accidentally violate later.

That's the actual test I use now. Not "is this clearer as a diagram" in the abstract, but whether future me, skimming fast under time pressure, still gets the constraint right. Prose degrades under skimming. A graph with a clearly labeled subgraph doesn't.

## What this changes about how I brief agents

Once I saw the difference, I stopped asking agents for write-ups and started asking for diagrams by default, whenever the subject is state, structure, or how systems connect. A dev board mermaid snapshot became a running fixture. Vault layout became a cheat-sheet table instead of a folder-by-folder essay. Anything with more than three interacting parts gets a graph before it gets a paragraph.

The box labeled "Never Published" is the whole argument in miniature. My brief left the company site off the list of surfaces, the first pass came back with seven sections and a lone content-engine node, and the missing boundary only showed up once the pipeline diagram put three lines on a page: one surface fed from the vault, one planned but unwired, one never touched. I had already written that rule in prose, and it slid past because it sat inside a sentence about something else. Drawn as a labeled box, it can't be skimmed past.