Visualisation vs Documentation

Product / Dualities · Added Oct 2026

If you can show the logic in the UI, don't just describe it in the docs.

The Tension

Complex software hides a lot: rules, workflows, calculations, state machines. You can explain them in documentation, or you can show them in the product itself. Docs are cheaper to write, so they usually win by default. Visualisation almost always serves the user better.

The Two Sides

Visualisation	Documentation
Uses the user's current data	Uses a generic example
Right there when needed	Lives somewhere else, has to be found
Shows why this case behaves this way	Explains how cases behave in general
Stays true as the logic changes	Drifts out of date quietly
Costs build effort	Costs writing effort

How to Navigate

Default to showing. When a user asks "why did this happen?", the answer should be one click away, in context.
Hide it until needed. A visual explainer doesn't have to crowd the screen. Put it behind an info icon, an expandable panel, or a "why?" link.
Use the real case. "Your invoice is £120 because 3 seats × £40" beats a pricing page with a formula.
Build it cheaply. With AI, a small diagram, timeline or breakdown view takes hours, not weeks. The old cost argument for docs is mostly gone.
Keep docs for the big picture. Concepts, onboarding and edge-case reference still belong in documentation.

Examples

A permissions screen that shows which role or group grants access, instead of a docs page on inheritance rules.
A pipeline run that draws the steps it took and where it stopped, instead of a page describing the pipeline.
A scheduling tool that highlights the conflict blocking a slot, instead of a help article on scheduling rules.

The Trap

Visualising everything, all the time. Explainers are for the moment of confusion. If they're always on, they become noise and the core UI gets harder to use.