Shapes

The five shapes of study documents, each derived from the topic of reader-ergonomics-topic and built on the shapes of reader-ergonomics, with the evidence behind each block and the checks a program runs on it.

Shape	Summary
lesson	a lesson or chapter studied alone: objectives, the explanation with its traps refuted, a question block per part, key points
question block	the questions at the end of each part: recall and application, tagged by objective, answers folded and explained
exercise sheet	each new type opened by a worked example, then a completion problem and a few problems; a mixed review; hints before answers
deck	flashcards shipped with study material: a header page and a file of cards, one question and one answer, each linked to its section
study guide	worked through before an exam: one problem solved per type, traps, variants, an error grid, a date to redo, a method sheet from memory
examples	one small document of each shape, on binary search, that passes every check

How they fit together

Five shapes. The lesson extends the core note; the exercise sheet's worked examples are core reports. The question block sits inside the lesson and the study guide; the deck derives from a lesson; the study guide draws on all four.

Graphviz source

digraph shapes {
  graph [rankdir=BT, nodesep=0.35, ranksep=0.6, 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", fillcolor="#E8EEF8", color="#2F5DA8"];
  edge  [fontname="Inter", fontsize=11, color="#3D434B", fontcolor="#55575F", penwidth=1.3, arrowsize=0.8];
  note   [label=<<b>note</b><br/><font point-size="11" color="#55575F">reader-ergonomics</font>>, fillcolor="#FFFFFF", color="#3D434B", style="rounded,filled,dashed"];
  report [label=<<b>report</b><br/><font point-size="11" color="#55575F">reader-ergonomics</font>>, fillcolor="#FFFFFF", color="#3D434B", style="rounded,filled,dashed"];
  deck   [label=<<b>deck</b>>];
  lesson [label=<<b>lesson</b>>];
  block  [label=<<b>question block</b>>];
  sheet  [label=<<b>exercise sheet</b>>];
  guide  [label=<<b>study guide</b>>];
  { rank=same; note; report; }
  { rank=same; deck; lesson; block; sheet; }
  lesson -> note   [label=<  extends>];
  sheet  -> report [label=<  worked examples>];
  lesson -> block  [label=<  holds>, constraint=false];
  deck   -> lesson [label=<  derives from>, constraint=false];
  guide  -> deck;
  guide  -> lesson;
  guide  -> block;
  guide  -> sheet;
}

Built on, not copied. The lesson keeps every block of the core note; a worked example is the core report, with its plan, its steps named by their goal and its fading.
Every shape is a topic: a title, a summary, a body, contents and see also (topic). The question block alone is a part, not a document.

The markup the checks read

Plain Markdown, so a document renders the same on GitHub, in Quarto and in Obsidian.

Thing	Written as
an objective	`- O1 <verb> ...` under `## Objectives`
a question	`1. O1 <question>` under a `Check yourself` heading, or a callout holding its answer, `> [!QUESTION]- Check: <question>`
a folded answer	`<details><summary>Answer</summary> ... </details>`, an Obsidian callout `> [!answer]-`, or a Quarto callout with `collapse="true"`
a trap	a quote opening `> Trap:`, or a callout titled Trap (`> [!warning] Trap`, `title="Trap"`), holding `Why not:`
a type of problem	`- T1 <type>` under `## Types`
an item of a sheet	`### Worked example (T1): ...`, `### Complete (T1): ...`, `### Problem (T1): ...`
a hint, an answer, a solution	folds whose summaries read Hint, Answer, Solution
a card	a row of a TSV file: front, back, source, tags
the shape a document follows	a line `Shape: [lesson](<link to the shape>)` under the summary

The labels Trap and Why not are tunables in checks/config.toml, so a French vault may write Piège and Pourquoi non.

Tested against study material written before them

The shapes were held out against two bodies of study material written before them, with predictions written before the count. One is every section of the 17 explained solution books of University-Coursework; the other, the S7 notes of the vault that goes with them.

In the books	Sections
What this tests, If you meet this again, Predict before running	102, 103 and 101 of 103
a trap, written as a callout titled Trap	101 of 103, 134 traps
a trap carrying a Why not label	0 of 103
objectives, a question block, a folded answer	0 of 103

A section of an explained book is a worked example: the core report, which is the study guide's part for one type of problem. It is not a lesson, and no shape was bent to fit it.
The markup changed twice, to read the authors' own forms. It reads a trap written as a callout, the form of all 134, and a question written as a callout with its answer inside, the vault's form.
The variants live in the vault, by design: that repository's rules give variants without a solution to the notes, not to the books. A book's section and its vault note together hold the study guide's part for one type.
The vault, checked with the questions check (no objectives asked of a note): 757 questions in 93 of 1,197 notes, every one folded; 10 answers are only a key. Its 48 traps, written as callouts titled Piège, refute in prose and carry no Pourquoi non label, the one difference between its convention and these shapes'.
What changed after the count: since neither body labelled a single refutation, a trap with no Why not is a warning, not an error: the program sees the label, not the refutation. The vault has since given its 48 traps a Pourquoi non line.

Declaring the documents to check

A repository that uses these shapes names its documents in its checks/config.toml, and copies this repository's checks/local/ beside its own:

[lesson]
files = ["notes/**/*.md", "guides/*.md"]

[sheet]
files = ["sheets/*.md"]

[deck]
files = ["decks/*.tsv"]

[questions]                       # notes: the question-block rules, no objectives asked
files = ["S7/**/*.md"]
trap_labels = ["Piège"]
why_labels = ["Pourquoi non"]

Shapes

Contents

How they fit together

The markup the checks read

Tested against study material written before them

Declaring the documents to check

See also