# Develop a directed explanation

A directed explanation changes what the viewer understands over time. Start with the inspected material and the question it raises, then choose the order of information and the arrangement that makes the change legible. [Directed scenes](directed-scenes.md) supplies the object/action grammar, [combinations](combinations.md) coordinates the actions, and [the playbook](playbook.md) covers page and presentation purposes.

## Choose the development before the layout

An explanation can follow cause to consequence, reveal a result then reconstruct its cause, compare alternatives, follow an investigation or show increasing scale. Choose from the audience's existing knowledge and the material. A surprising result may make a stronger opening than a definition; a support procedure may need the operation immediately. A layout kind is a spatial tool, not a story formula.

Give each scene a change: identify an owner, make a relation visible, demonstrate a transfer, reveal a boundary, compare results or locate a control. Consider the intended response as well: confidence in evidence, curiosity about a mechanism, tension before an outcome, relief after a repair. An entrance, depth treatment, shift of scale or calm hold can give a meaningful moment weight. Useful effects are available throughout the vocabulary; avoid turning a caution against decorative defaults into a ban on expressiveness.

## Preserve identities and relations

Keep component names, responsibilities and locations stable while example values develop in named slots or a separate region. Replace an object body when it is genuinely a changing value; do not rotate unrelated explanations through one architectural component. A copy preserves its original; a transfer empties its temporary source on arrival. A connector, direction of travel, corresponding position or repeated identity can show how two views relate. The viewer should be able to attribute a consequence to its cause, not reconstruct the relation from unrelated narration.

Every system interface has a specific spatial requirement: show the complete captured application viewport before its fragment, in pages, presentations and films of every aspect ratio. Keep an overview beside a detail, show the whole image first or use a spotlight/loupe. Establish a substantially different screen after navigation. The overview need not make every label readable; the later detail view does. It is the viewport, not the complete long document. Automatic portrait conversion cannot restore a whole screen absent from the source.

This requirement does not turn every subject into whole-to-detail staging. A mechanism can begin on a result, a comparison on two states, a data scene on a surprising observation. They still need understandable identities, relations and change.

## Use an arrangement that gives the material room

`diagram-code` places shorter code beside its mechanism. `pipeline`, `before-after` and `ownership` give a code object a full-width row below their visual objects, which suits longer lines and multi-result comparisons. `overview-detail` retains context while explaining a fragment. Choose another view or a reading close-up when a complex graph and many lines cannot both be read at film scale.

A real screenshot may have a perspective presentation without becoming fabricated evidence. Settle for detailed reading, keep evidence colors truthful and label reconstructed UI or pseudocode. Pointer depth/tilt is a reader interaction; it is not automatically a filmed camera orbit. Select timed composition actions for state change and the film tool's camera or loupe for a reading close-up.

## Alternatives for the same material

For a first local edit, a causal staging establishes the owners, copies their value, highlights the operation, edits and compares. A result-first staging opens on the divergence and reconstructs why the original survives. A product walkthrough begins on the whole real UI, shows the actual edit and enters the mechanism afterwards. The source facts stay the same while information order and emphasis differ.

For a shared input producing two results, synchronized changes emphasize a common trigger. A sequential investigation follows one path, raises the question about the other and exposes their difference. An overview beside a close-up emphasizes location instead. Combine these when the subject needs several relations, using a clear attention hierarchy rather than a fixed recipe quota.

## Let data choose its picture

Use a chart with a common scale, paired figures or a sourced before/after when the material is numerical. A transfer would imply an operation the data may not support. Keep units, period, sample and limitations beside the associated values, inside the filmed target; a long qualification should not dominate the main comparison. The `source` object role means a baseline or originating value, not a bibliographic citation. Put provenance in a source line or nearby note when it needs no action of its own.

## Distinguish reading from filming

A reader can scroll, pause, change a view or request reduced motion. A film viewer receives a fixed sequence, so narration, action and reading need deliberate timing. Bind filmed `bN` cues to measured narration; the standalone three-second convention is a preview. Give dependent actions enough arrival time and keep the completed state stable when it must be read. A still hold can establish, explain or emphasize a result; a static page with unrelated changing captions does not demonstrate a mechanism.

Keep reduced-motion, print and script-free equivalents intact. Page guidance about restrained autonomous motion protects reading; it does not prohibit coordinated timed movements in a filmed explanation. A coherent expressive scene may combine a transfer, corresponding line focus, a connector and a following camera when those describe the same event.

For an architecture or code film, use [architecture films](architecture-films.md): a concrete operation, its actual callers/callees, arguments/results, owners and event boundary develop together with the matching code. `midnight` with a dark scheme is the starting look for this material.