> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing Panes that explain well

> Name, describe and arrange Panes so Plotted Path explains any answer to a reader who knows nothing about how it is built.

## Sources

Docs: [Panes](/ponder/parables/pieces/panes.md), [Perceptions](/ponder/parables/pieces/perceptions.md), [Policies](/ponder/parables/pieces/policies.md), [Preferences](/ponder/parables/pieces/preferences.md), and [Plotted Path](/ponder/parables/sandbox-design-system.md#ponder).

Web App: hover a Pane that reads data and choose **Plot the path to this…**.

## Who reads what you write

**Plot the path to this…** explains how the thing a reader points at came to
be, from the tools its information comes from up to that Pane. Every
Parable gets it, and nothing about it is written for one Parable. It is
written from what the Parable already says about itself:

* each Pane's name and description;
* which Panes each Pane builds on, through the Panes it declares, the Plots
  of this Parable its Plot reads, and the Plots its filter conditions name by
  key. A Plot of another Parable is not part of the path, even when its slug
  is the same as the slug of one of this Parable's Plots;
* which Panes have settings people can change;
* the access Policies on the path and on the Page;
* the Provider tools at the bottom.

The reader is a CEO or an intern. They know nothing about code, databases or
how the Parable is built, so the explanation can only be as clear as the
names and descriptions it starts from.

## Write names and descriptions for readers

A Pane's name and description are the words a reader sees. Write them for the
person reading the Parable, not for the person editing it.

| Instead of | Write |
| - | - |
| `Orders by region (join)` | Late orders by region |
| Joins orders to shipments and filters status = 'late'. | Orders that arrived after the date promised, by the region they shipped to. |
| Keeps the lowest id per customer as the canonical row. | One record per customer, even when they signed up twice. |

* Say what the Pane shows or decides, in one or two sentences.
* Leave out how: no queries, joins, columns or function names.
* Leave out detail a reader would not act on.

## One Plot per Pane

A Pane owns at most one Plot. A second computation gets a Pane of its own,
which the first one declares or reads. The explanation follows Panes, so each
step a reader opens is a Pane with a name and a description of its own.

## Put sources under their type

Model what a Parable is about as Panes of their own, such as a Meeting, a
Person or a Message, and put each tool's source under the type it feeds:
a Meeting Pane declares its Google Calendar and Zoom Panes. An explanation can
then say "We gather meetings from your calendars and calls" and let a reader
open the Meeting Pane, rather than walk every source one by one.

Label a row type's place in that model with `@grouping` in its Perception's
doc comment, for example `/** A Meeting. @grouping Activity › Meetings */`. It
is a convention: Plotted Path does not read it.

## Mark plumbing

Some Panes only serve other Panes: shared state, a kit of helpers, a preview.
Mark each with `@plumbing` in the doc comment on its `Perception`, so the
explanation never offers it to a reader as a part to open:

```ts theme={null}
/** Shared state the other Panes read. @plumbing */
export interface Perception extends BasePerception<null> {
  readonly panes: {};
}
```

The mark is saved in the Pane's manifest
([Perceptions](/ponder/parables/pieces/perceptions.md#schema)). The Panes it
serves still say what they build on.

## Name access Policies in plain words

The explanation quotes the filter Policies on the path and on the Page by
name, for example "People only see categories and hours within their own
reporting line". Name a Policy for what it does to a reader, such as
**My reporting line**, not for how it works.

## Words a reader never sees

The explanation never uses database, programming or builder words. It is
checked against this list, matched as whole words in any case, and written
again once, naming the words it used:

> jev, row, rows, column, columns, table, tables, schema, data model, query,
> queries, sql, join, joins, null, kind, kinds, report run, report runs, plot,
> plots, draws nothing, preview, previews, record type, record types, inline,
> section, lowercase, lower case, identifier, identifiers, username,
> usernames, helper

Product words such as Pane, Parable, Perceptions, Policies, Proof, Ponder,
Provider, Workspace and Team are not on it: the sheet itself names "The
**Person** Pane". The explanation is written from your names and
descriptions, so keep these words out of them too: the editor names any it
finds in a Pane's name or description, under the description.

A step's linked Pane opens in a side panel with its description. There a
reader sees every sentence of it except one that names something from the
code, such as a Plot's handle: "It owns the `personRows` list." is left out,
and a description with nothing else to show shows none. A sentence you wrote
in ordinary words stays, the words of the list above among them: "One row per
person." is shown as you wrote it.

## How the explanation is written

The server builds a map of the Pane for the whole Version: each Pane with its
name and description, what it builds on, whether it has settings, the
Provider tools at the bottom, and the access Policies in plain words. A
`@plumbing` Pane is left out, and what it builds on passes to the Panes that
read it.

One language call explains the map, through the Workspace's
model for **Ponder's explanations and summaries**. That model is Haiku Latest by
default, routed through OpenRouter with zero data retention, so the
Workspace's AI processor rules apply. It answers in a few steps, each a
title and short bullets, linking the Panes a reader would open next, written
from where the information comes from up to the Pane: the first step is
always where the information comes from. The sheet numbers them in that
order. An answer that comes back incomplete, such as a single step with no
bullets, is asked for once more, saying what was missing. One still
incomplete is never kept or shown: the reader is told the explanation failed,
and the next open asks again.

The map never names a part fewer people may view than the Pane itself. A part
whose view Policies are stricter, by participation level, people and Roles,
the setting they follow, or a view filter Policy of its own, is left out, with
everything reached only through it, and the access rules say only that some
of what the answer builds on is not described. When the explanation is shown,
each link is checked again against the reader's own seat, so nobody sees a
link to a part they cannot open.

The platform keeps one explanation per Pane and published Version, with the
map it explains and the version of the instructions that wrote it, and serves
it to everyone who may view the Pane. A new Version whose map for the Pane is
unchanged keeps the explanation it had, with no new call. When the map or the
instructions change, the kept one is shown while a new one is written. An
earlier Version's explanation is shown that way only when every part it was
written from is still in this reader's map: its titles and bullets may name a
part whose view has since become stricter, and only links are checked when it
is shown. Otherwise the new one is written before it is shown. A Pane nobody has
opened yet is explained the first time someone does. Someone who publishes the
Parable can ask for it to be written again. A set of unpublished Changes is
explained each time it is asked, and never kept.

## Write it ahead

A Pane readers open often can have its explanation written before the first
of them opens it. Say when with `@plottedPath` in its Perception's doc comment:

```ts theme={null}
/** Hours by category for the dates you picked. @plottedPath publish */
export interface Perception extends BasePerception<null> {
  readonly panes: {};
}
```

* `@plottedPath publish` writes it as each Version is published from the
  editor.
* `@plottedPath report` writes it as each Report run of a Version completes,
  for a Parable read mostly from its Refreshes.

It is written in the background, one Pane at a time, for the Page the Pane is
shown on, and skipped when the kept one already explains the same map. Any
other word after the tag is refused when the Perception is saved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.