DEV Community: Xinwei

A Spreadsheet Is Not a Story: A Four-Scene Brief for Decision-Ready Explainers

Xinwei — Mon, 03 Aug 2026 13:47:18 +0000

Most spreadsheet updates fail for a simple reason: they show the evidence before they name the decision.

The numbers may be correct. The workbook may be carefully maintained. But the person opening it still has to answer four questions for themselves:

What changed?
Compared with what?
Why does the change matter now?
What should happen next?

That is why a narrated explanation should not become a screen recording of a worksheet. The useful unit is not the cell. It is the decision behind a small, reviewable set of cells.

Start with one viewer question

Before choosing a chart or a scene, write a sentence that a decision-maker could ask aloud.

For example:

Did fulfilment performance improve after the routing change, and should the team extend it to the remaining regions?

That question gives the source material a boundary. It tells you which period, comparison, assumption, and next action belong in the explanation. It also makes it easier to remove everything that is merely adjacent.

A four-scene brief

Here is a compact pattern that works for KPI exports, operating dashboards, financial workbooks, and survey comparisons.

Scene 1: Establish the decision and the time window

Show the decision in plain language, then anchor the analysis to a period. A single line such as “Week 26 after the routing change” is more useful than opening on a dense dashboard.

The reader should know whose decision this is and what timeframe is in scope before seeing a percentage.

Scene 2: Show the comparison, not every value

Choose the baseline that makes the decision meaningful: before/after, plan/actual, cohort A/cohort B, or current/proposed.

Use a small number of values with their units and definitions. If the comparison is not valid because the population, filter, or calculation changed, say that instead of animating a misleading trend.

Scene 3: Explain the mechanism or constraint

This is the scene dashboards usually omit. A metric moved, but what operational condition changed with it?

For the routing example, the explanation might show a simpler handoff path, the affected regions, and the constraint that still prevents rollout everywhere. The viewer does not need every implementation detail. They need the relationship between the change and the outcome.

Scene 4: End with the decision, owner, and review condition

An explanation should give the viewer a next move. That might be “extend the pilot after the data owner validates the final two regions,” not “the project succeeded.”

The final frame can keep three things visible:

the recommended action;
the owner of the validation; and
the condition that would change the decision.

That makes the content useful in a meeting and still reviewable afterwards.

Keep the workbook as evidence

An explainer should make evidence easier to understand. It should never replace validation.

Before sharing, the data owner should still check the source period, filters, units, calculation, comparison baseline, labels, and conclusion. Link or attach the workbook where the audience needs to inspect it. If a number changes, update the source and the explanation together.

This division of labour is important: the spreadsheet remains the auditable evidence; the visual sequence helps a human follow the comparison and decision.

A prompt is not enough; provide a brief

When you create a source-led explainer, include the following with the selected workbook or chart:

Viewer: regional operations lead
Question: should the routing pilot expand?
Period: weeks 22–26
Comparison: pilot regions vs. their own pre-pilot baseline
Evidence: order volume, fulfilment time, exception rate
Constraint: two regions use a different handoff process
Decision: extend only after exception-rate review

This is short enough to review, but it prevents the common failure mode of turning every visible metric into narration.

Where this workflow fits

KPainter is the source-to-explainer workspace I founded. Its Excel-to-video workflow starts from a workbook, chart, or selected data range and asks for the metric, comparison, audience, and decision that the viewer needs to understand.

The important part is not the tool. It is the reviewable brief: one question, one valid comparison, a visible mechanism, and a named next step. With that structure, a spreadsheet update can become something a team can understand before the meeting rather than a file they open during it.

Xinwei is Founder of KPainter.

Release Notes Are Not Product Education: Build a Decision-Oriented Walkthrough

Xinwei — Mon, 03 Aug 2026 12:41:30 +0000

Release notes answer an important question: what changed?

About this method: I build KPainter, a source-to-explainer video workspace. KPainter helps teams turn release notes, product briefs, docs, screenshots, and other source material into clear explainer videos. The workflow below keeps the maintained source—not the video—as the source of truth.

They are not always enough to answer the next questions a customer, support teammate, or implementation partner has:

Does this change affect my workflow?
What should I do differently?
What is deliberately unchanged?
Where can I check the current details when the product evolves again?

That difference matters when a team turns a changelog, launch note, or technical update into a walkthrough. A screen recording can show a new control. A useful explanation helps the viewer decide whether to care, what to try, and where the boundary is.

Start with the viewer's decision

Before opening a recorder or drawing a storyboard, write one sentence in this form:

After this walkthrough, [viewer] should know whether [change] affects [their job], and what to do next.

For example:

After this walkthrough, an existing workspace administrator should know whether a new approval step changes their release process, and where to configure it.

This sentence prevents a common failure mode: putting every release-note bullet into a video. A list of features is complete, but it is rarely a clear path through a decision.

Establish the source hierarchy

Product details have different lifetimes. The launch note may be a useful summary, while the maintained documentation defines the exact configuration, permissions, availability, or limits.

Use a small source hierarchy before drafting scenes:

Current product documentation — the maintained source for setup, constraints, and terminology.
The release note or change record — why the change happened and the scope of the release.
A verified product view — the interface or workflow that a viewer should recognise.
Support or migration guidance — exceptions, rollout questions, and an escalation route.

Each claim in the walkthrough should have an owner. If an availability detail changes next week, the maintained page should be the thing that changes first; the video can point back to it rather than becoming a second source of truth.

Build five beats, not a feature tour

For a short walkthrough, five beats are usually enough:

Beat	Viewer question	Evidence to show
Context	Why would I notice this?	The workflow or outcome before the change
Change	What is different?	One named capability or decision point
Fit	Does it affect my role?	A role, condition, or example use case
Boundary	What has not changed or is not covered?	Availability, permission, or scope limit
Next action	What should I do now?	The current documentation, setup step, or support path

The order is deliberate. Showing a new interface first often forces viewers to infer why it matters. Context gives them a reason to look; the boundary protects them from assuming more than the change actually delivers.

Keep the live product separate from the explanation

A walkthrough should not freeze a product UI into a promise. Use the current interface as evidence only when it is stable enough for the point you are making. If the exact layout is likely to move, show the outcome or decision rather than a sequence of pixel-level clicks.

Likewise, preserve the difference between a reported fact and a recommendation:

Fact: a setting is available to a specified role.
Recommendation: a team might use it during a defined review step.

That distinction is especially useful for release notes because product teams often combine confirmed behavior, rollout timing, and suggested practices in one announcement.

A reusable planning brief

Use this before writing narration or choosing visuals:

Viewer and moment of use:
Change the viewer needs to understand:
Current maintained documentation:
Release-note source and version/date:
One workflow or decision to make visible:
Who is affected, and who is not:
Boundary, rollout condition, or exception:
Viewer's next action and the maintained destination:
Review owner and update trigger:

KPainter's open release-notes product-education brief turns those fields into a copyable worksheet.

Review before publishing

Ask a product owner, support lead, or documentation owner to check four things:

Terminology — are feature and role names current?
Scope — have availability, permissions, and exceptions been stated accurately?
Decision path — can the named viewer tell whether to act, without guessing?
Maintenance — does the final screen direct the viewer to the current source?

The purpose is not to replace release notes. It is to turn a change record into a path a real person can follow, while keeping the maintained source in charge of the details.

To turn a change record into a source-led explainer workflow, read KPainter's guide to release notes and explainer videos.

How to Turn an Architecture Guide into Developer Onboarding

Xinwei — Fri, 31 Jul 2026 16:01:11 +0000

An architecture guide often answers the wrong question for a new contributor.

It tells them what components exist, where repositories live, and which services talk to each other. All of that matters. But a person joining a codebase usually starts with a more practical question: what is this system trying to accomplish, and where can I make a safe first contribution?

That difference is why many technically accurate onboarding documents remain hard to use. The reader receives a component map before they have a job model.

Here is a structure for turning an existing architecture guide and release checklist into an onboarding walkthrough that helps a contributor orient themselves without flattening the technical detail.

1. Start with the system job

Open with the user-facing or operational job the system performs. One or two sentences are enough. A contributor needs a causal anchor before a list of services means anything.

For example, instead of beginning with “the platform has an API, worker, queue, and web client,” start with the flow the system enables: a request enters, work is validated, a background process completes it, and a user receives a reviewable result. The component map then becomes an explanation of how the job is carried out.

2. Group components by responsibility

Avoid a tour of every repository. Group the architecture into responsibilities the contributor can remember:

entry points that receive a request;
services that validate or orchestrate it;
workers that perform longer-running work;
storage or state that keeps the result available;
interfaces where users review or continue the work.

This does not hide implementation detail. It creates a first-pass model that makes detail searchable later.

3. Show one request end to end

An onboarding walkthrough needs a concrete path. Choose one representative request and trace it across the boundary between components. Show what enters the system, what changes state, what work is asynchronous, what result returns, and where a failure is surfaced.

The path should include the terms a contributor will encounter in logs, pull requests, and issues. Stable labels are more useful than animated diagrams with generic boxes.

4. Connect the release checklist to the architecture

Release documents are often separated from architecture documents, even though they teach the contributor where responsibility actually lives. Pair a release action with the component or dependency it affects.

For each release step, answer:

What is changing?
Which component owns that change?
What dependency or configuration makes the change live?
What observable result confirms it worked?
What is the rollback or escalation path?

This is where an abstract diagram becomes an operating model.

5. Design the first-contribution path

New contributors do not need every internal decision on day one. They need one safe route from orientation to a meaningful change.

Describe:

the local setup boundary;
a small issue or documentation change that exercises the normal workflow;
tests or checks that establish confidence;
the reviewer or owner for the relevant area;
the signal that tells the contributor they are ready for a larger task.

The path should be visible in the same walkthrough as the architecture. Otherwise the reader learns the system but not how to participate in it.

6. Keep the guide maintainable

Architecture onboarding becomes misleading when it is polished once and left alone. Give it an owner, a revision trigger, and a short glossary. Update the request path when a dependency or release flow changes. Keep links to the detailed architecture reference for people who need depth.

A compact storyboard

For teams making a visual walkthrough, a dependable sequence is:

system job;
core responsibilities;
one request path;
one release or operating path;
one first contribution;
links to deeper references and owners.

For a visual companion to this method, see KPainter's architecture-onboarding explainer example. The important lesson is not the visual treatment. It is the order: explain what the system is for before asking a new person to memorize its parts.

Xinwei is Founder of KPainter, a source-to-explainer video workspace. This is an original documentation-design article; teams should adapt the structure to their own architecture and security boundaries.