Topic

Checks against reader-ergonomics Site

One template for a unit of writing, called a topic, whose parts can be topics of the same template. Any body of information is then written as a tree that reads the same way at every depth.

The name is the field's own. A topic is the unit of DITA and of topic-based authoring (information typing). Document models call the same unit a content object (document model), and studies of trees on screen call it a node (progressive disclosure).

This page in French: README.fr.md.

Status: one template, the topic; its check; and three multivocal reviews of 218 sources, done 2026-10-29, in evidence. No reader study has tested the template. Its gain over DITA's base topic is stated as a test with four outcomes (baseline), none of them run yet. The AI-augmented strand, on checking reasoning written as topics, left for a repository of its own the same day (0016). It is not an official standard, not a peer-reviewed study and not a new result.

How it is made: with Claude, an AI assistant by Anthropic, under the maintainer's direction, the way reader-ergonomics was made. Corrections are welcome as issues.

Take it

The topic is meant to be copied and kept as your own. Copy it from a tagged release (tags), so a later change here never changes your copy.

  1. Copy shapes/topic.md, the shape, and checks/local/topic.py, the check, into the same paths of your repository.

  2. Write your topics: each a file with a title and a summary, each folder's README listing its children with theirs.

  3. Add checks/config.toml; the last two tables are for a repository with no site stylesheet:

    extends = "reader-ergonomics"

[topic]
files = ["README.md", "docs/"]   # your topics: files and folders
root = "README.md"

[readable_measure]
stylesheets = []

[sufficient_contrast]
stylesheets = []

  4. Run the standard's checks at the commit the release pins (ref: in its checks.yml); the topic check runs beside them:

    git clone https://github.com/Tewf/reader-ergonomics
git -C reader-ergonomics checkout <the pinned commit>
python3 reader-ergonomics/checks/run.py path/to/your/repository

  5. How to take your own version of the family, and where a disagreement goes: the standard's Take your own version.

Where it sits

Three levels: learning pins the topic and other projects may use it as a skeleton; the topic obeys reader-ergonomics, whose checks its CI runs.
Graphviz source 
digraph where_it_sits {
  graph [rankdir=TB, 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];
  LE [label=<<b>reader-ergonomics-learning</b><br/><font point-size="11" color="#55575F">level 2</font>>, fillcolor="#E6F2EA", color="#2E7D4F"];
  OT [label=<<b>reader-ergonomics-academic, -presentations,</b><br/><font point-size="11" color="#55575F">-software-design, other projects</font><br/><font point-size="11" color="#55575F">level 2</font>>, fillcolor="#E6F2EA", color="#2E7D4F", style="rounded,filled,dashed"];
  TO [label=<<b>reader-ergonomics-topic</b><br/><font point-size="11" color="#55575F">one topic shape, nested to any depth,</font><br/><font point-size="11" color="#55575F">its review and its check</font><br/><font point-size="11" color="#55575F">level 1</font>>, fillcolor="#FBEDE4", color="#B4541A", penwidth=2.6];
  RE [label=<<b>reader-ergonomics</b><br/><font point-size="11" color="#55575F">how any text serves its reader</font><br/><font point-size="11" color="#55575F">level 0</font>>, fillcolor="#E8EEF8", color="#2F5DA8"];
  LE -> TO [label=" pins a release; its shapes\l will derive from the topic\l"];
  OT -> TO [style=dashed, color="#6A6D77", label=" may use the topic as their\l skeleton (a hypothesis)\l"];
  TO -> RE [label=" obeys the principles; CI\l runs their checks here\l"];
  {rank=same; LE; OT}
}
  • It obeys reader-ergonomics, so it sits one level above it, and a project that uses it sits above it in turn. No level depends on a level above it.
  • reader-ergonomics never links to it: the standard links to no extension (extending.md). This repository links down to the standard, never up to the extensions.
  • One extension says it will use it: reader-ergonomics-learning pins a release and states that its shapes will derive from the topic; none is written yet. That the others will use it is a hypothesis. If none does, this repository still answers one question.

Scope

What Why
in the evidence on recursive templates, from the reader's side the reader is the object, as in reader-ergonomics
in the topic shape: the blocks every topic has, and how a topic holds or points to other topics one template, kept in one place
in one check a program runs on a topic at any depth what a program can check, a program checks
out the genres: papers, proofs, talks, design documents they stay in their own repositories
out what a research claim is, how it is proved or verified another problem, with its own evidence; the strand that took it up left for a sibling repository (0016)

What the review found

Each answer links the review that holds its evidence; a grade says how strong that evidence is.

Question Answer Grade Review
Depth. Readers recall the top levels best, and reader-ergonomics caps an outline at three levels. Can the recursion be unbounded in storage and capped in what a reader sees? Yes, as a design, under three conditions: the path to the root is shown, what most readers need sits above the first fold, and each folded topic shows a summary. Readers rarely open a second layer, and for agents a second level of folding never helped. supported with caveat; never tested directly progressive-disclosure
Self-reference. A topic type whose children are topics gives a tree; a topic that contains itself is a cycle. Which does the template need? The recursive type only. Every document model read keeps each instance a finite tree, and forbids, reports or caps a cycle, or leaves it undefined. convention, across 14 systems document-model
Graphs. A topic used by two parents no longer forms a tree. Is the tree only the storage, and the graph the meaning? The standards store a graph of trees and give each reading one tree: one containing parent, any other parent by reference. No study of how readers meet a reused unit was found. convention; the reader side is a gap document-model
Genres. Is the topic what the genre shapes share, or a rival to them? What they share, as practice already does: DITA derives concept, task and reference from one base topic. Typing alone showed no learning gain in Horn's own 1969 test (19.56 against 17.65, 41 students). Whether a reader who knows the base reads a derived type better is untested. convention; the transfer is this repository's open question information-typing

The baseline the topic must beat

Reader Baseline Control
a person, the unit and its types the DITA 1.3 base topic with its concept, task and reference types, its maps and its reuse by reference, validated, cycles reported the same content as untyped prose
a person, the tree on a page the same content as one document of at most three heading levels, its contents always visible beside it the fully expanded tree
a model passages retrieved in the document's own order, at a matched token budget a tree of summaries

The comparison measures finding, gist against detail, recall after a delay, transfer to a derived type never seen, and what a program check catches. Each review's baseline.md gives the design.

The topic template

Part Summary
shapes the topic, the base every shape derives from, and how the four general shapes of reader-ergonomics fit it
the check runs on every topic of this repository, at any depth: title, summary, listed by its parent with that summary, no inclusion cycle
decisions one record per architectural choice, each opening with the decision in one sentence
  • The topic has five blocks: title, summary, body, contents and see also. Each is traced to a principle of reader-ergonomics and to the evidence here (topic).
  • The four general shapes all fit, with two renames and one merge: a commit's subject line is both its title and its summary. They are the material the topic was drawn from, so the fairer test is the next line (the table).
  • On six forms of the genre extensions it was not built from, five fit; a decision record with no summary does not. Run on those three repositories, 113 documents, the check finds 7 faults once their review steps are declared, in that run's configuration as types.
  • The decision record, first written here, now lives in reader-ergonomics (v1.3.0). This repository's records follow it, and the check verifies that each one says so.
  • This repository is its own first tree of topics: the check runs on it in CI, and the tests of the check are in checks/test_topic.py.

Next

  1. Compare the topic with the baseline above, on readers: the design is in each review's baseline.md.
  2. The genre extensions may derive their shapes from the topic; each would say so in its own repository.

Check it

git clone https://github.com/Tewf/reader-ergonomics
python3 reader-ergonomics/checks/run.py path/to/this/repository

CI runs the same checks on every push, and a run fails on any error (checks.yml). Every push to master also renders the site, tewf.github.io/reader-ergonomics-topic (pages.yml).

Licence

Code under the Apache License 2.0; prose under CC BY 4.0. Reuse it as you wish, with credit to this repository; CITATION.cff gives a citation if you need one.