Shape: topic

The base every shape derives from: a unit of writing with a title, a summary that stands for it, a body, and the topics it contains or points to. A genre shape adds blocks to it and removes none.

A topic is one unit of writing that a reader can take alone. Its parts may be topics of the same shape, to any depth.

Skeleton

# <Title: what the topic holds, in the field's words>

<Summary: one to three sentences that stand for the topic wherever it is folded or listed.>

<Body: the parts, in the order the reader needs them.>

## Contents          the topics this one holds, each by its title and its summary;
                     omit the section while there are none

| Topic | Summary |
|---|---|
| [title of the child](child.md) | the child's summary |

## See also          topics this one points to without holding them: its parent, and related topics

A filled topic, short enough to read whole: the decisions folder, whose summary stands for the folder and whose Contents table lists each record by its title and summary.

The blocks

Block	Rule	Principle	Evidence
Title	one per topic; it names what the topic holds	names predict content	DITA requires a title on every topic (information typing)
Summary	right after the title, or after its metadata (a byline, a status); at most 60 words; it may be labelled Abstract or Summary; it stands for the topic when folded or listed	overview first	a folded node must carry a summary (progressive disclosure)
Body	the parts in the reader's order; at most three heading levels	shallow outline	readers keep the top levels best (levels effect, reader-ergonomics psycholinguistics)
Contents	each child by its title and its summary, or by its type alone when the type's role is stated once	signal the structure	readers rarely open a layer they cannot judge from outside (progressive disclosure)
See also	links, never copies	one place per fact	the standards reuse by reference (document model)

The 60 words are a tunable: summary_words in checks/config.toml, PROVISIONAL until a reader study sets it.

How a shape derives from it

Note, report, folder and commit each derive from the topic shape and add their own parts.

Graphviz source

digraph topic_shapes {
  graph [rankdir=BT, nodesep=0.4, ranksep=0.5, bgcolor="white", pad=0.2, fontname="Inter"];
  node  [shape=box, style="rounded,filled", fontname="Inter", fontsize=13, margin="0.2,0.1", penwidth=1.5, fontcolor="#1F2328"];
  edge  [fontname="Inter", fontsize=11, color="#3D434B", fontcolor="#55575F", penwidth=1.3, arrowsize=0.8];
  TP [label=<<b>topic</b><br/><font point-size="11" color="#55575F">title · summary · body · contents · see also</font>>, fillcolor="#FBEDE4", color="#B4541A", penwidth=2.6];
  NO [label=<<b>note</b><br/><font point-size="11" color="#55575F">+ terms + check yourself + open</font><br/><font point-size="11" color="#55575F">see also: Links</font>>, fillcolor="#E6F2EA", color="#2E7D4F"];
  RP [label=<<b>report</b><br/><font point-size="11" color="#55575F">+ what it tests + plan and steps</font><br/><font point-size="11" color="#55575F">+ checks</font>>, fillcolor="#E6F2EA", color="#2E7D4F"];
  FO [label=<<b>folder</b><br/><font point-size="11" color="#55575F">+ example + rules for the folder</font>>, fillcolor="#E6F2EA", color="#2E7D4F"];
  CO [label=<<b>commit</b><br/><font point-size="11" color="#55575F">title and summary share one line</font>>, fillcolor="#E6F2EA", color="#2E7D4F"];
  NO -> TP [label=" derives from"];
  RP -> TP;
  FO -> TP;
  CO -> TP;
  {rank=same; NO; RP; FO; CO}
}

Keep every block. A derived shape keeps all five. It may call a block by another of its accepted names, from the table below, and by no other. It may leave Contents or See also empty while there is nothing to hold.
Title and summary come first, in that order: they are what a folded view shows. Only metadata may stand between them. The other blocks may be ordered by the shape.
Add, never remove. A shape adds its own blocks, such as a note's Check yourself.
Announce the type. A document links the shape it follows, so a reader knows which blocks to expect, and the check knows which to look for.
Grade: convention, untested. Whether a reader who knows the topic reads a derived shape better is the open question of information typing.

The accepted names, in one place. A shape that needs a new name adds it here first, with the shape that uses it:

Block	Accepted names	Used by
Title	the one `#` heading; a subject line	every shape; a commit
Summary	summary, abstract, short description, decision	the topic; papers; DITA; the decision record
Contents	contents, files, steps	the topic and a folder; a review's README; a report
See also	see also, links, references, uses	the topic and a folder; a note; papers; a proof

The decision record was first written here, then moved down to reader-ergonomics (v1.3.0), where three levels can link it; it fits the topic like the four general shapes. The topic's own derived shapes will come from its extension.

The four general shapes of reader-ergonomics, and six forms of the genre extensions it was not built from, are checked against these rules in the conformance table. Five of the six fit; a decision record without a summary does not.

Depth

In storage, any depth. A topic may hold topics that hold topics. In this repository the front page holds the evidence, which holds three reviews, each holding its steps: three levels below the root, each topic listed by its parent with its summary.
In view, at most three levels. A view shows the topic, its children by their summaries, and one level more.
The path to the root is always there. A topic read alone names its parent in See also; the site shows the full path.
What most readers need sits in the summary and the first part of the body, above the first fold.
Grade: supported with caveat, never tested as such (progressive disclosure).

Graph

One containing parent. A topic lives in one place: in a repository, one folder or one file.
Any other parent points to it. It links the topic and never copies it.
No topic contains itself, directly or through an inclusion, at any depth. In a repository, containment follows folders, which form a tree, so it cannot loop; a cycle can come only from an inclusion, such as a Quarto {{< include >}}, and that is what the check looks for.
Grade: convention, the rule of every document model read (document model).

When a part becomes a topic

A part of a topic is a section of its file until one of these holds; then it becomes a topic, in a file of its own.

It is used from a second place. A unit with two parents is reused by a link, never by a copy or a second nesting (document model).
A reader can take it alone. It has a summary that stands for it without its parent, the topic's own definition, and it carries what its reader needs without its first context.
Its role differs from its parent's. It follows another shape, or it changes for other reasons, as reader-ergonomics' one role per file asks.
It would take its parent past three levels of headings. The outline stays shallow; the deeper part moves down a level of topics instead.

Otherwise it stays a section: a part cut from its context loses it, as translators of segmented content report (Batova 2014, through the document model review). The check reads files, so a section is never a topic.

Grade: convention, untested, drawn from the rules above; no study measured when to split.

The check

checks/local/topic.py runs on every topic declared in checks/config.toml, at any depth:

Rule	Kind
one title, and it opens the topic	error
a summary right after the title, or labelled within its first blocks	error
the summary within `summary_words`	warning
listed by its containing topic, so it can be reached from the root	error
listed with its summary, or by its declared type, not as a bare link	warning
no inclusion cycle	error

Heading depth, links that resolve and the headings a shape requires are checked by reader-ergonomics itself.