Learning materials
How to write material meant to be learned, so that someone who studies it alone retains it and uses it on new problems, at the least cost. The material is the lesson, the worked example, the exercise sheet, the study guide, the flashcards, and the questions inside them.
This page in French: README.fr.md.
Write a lesson
Copy the example lesson and keep its headings: Objectives, Terms, each part with its Trap and Check yourself, Key points, See also. Point its Shape line at the lesson shape by URL,
https://github.com/Tewf/reader-ergonomics-learning/blob/<commit>/shapes/lesson.md, and its See also at your own files.Declare it in your repository: copy this repository's checks/local/ into yours, and name the file in
checks/config.toml:[lesson] files = ["lesson.md"]Run one command, with reader-ergonomics cloned beside it at the release this repository pins, v1.18.2 (
bfbe9f7):python3 ../reader-ergonomics/checks/run.py .An objective no question tests, or an answer left in sight, is an error.
The other four work the same way: shapes gives the exercise sheet, the deck, the question block and the study guide, each with its own example.
Take it and keep your own
The family's form is the standard's Take your own version; for these shapes:
- Copy at a commit of this repository, and note it: what you copied is yours, and nothing done here later changes it.
- Pin the standard by commit, as this repository does, and move the pin when you choose:
git clone https://github.com/Tewf/reader-ergonomics ../reader-ergonomics && git -C ../reader-ergonomics checkout bfbe9f7(v1.18.2). - Run the checks: the command above. A run with no error is the result; the questions it leaves for judgment, in
checks/out/needs-judgment.md, never block it. - A disagreement about a study document, a rule that stops a real writer or a grade you doubt, goes to this repository's issues; the standard's section says where the others go.
The five rules that matter
| Rule | Grade | Checked |
|---|---|---|
| every objective is tested by a question, and every question names its objective | convention: every template read does it, no trial tests it | error |
| each part ends in questions answered from memory, the answers folded | measured, for retrieval | error |
| a trap states the wrong idea, marks it wrong, then gives the accepted one | measured: refutation beats plain exposition, g = 0.36 over 30 comparisons | warning, without a Why not |
| a new type of problem opens with a worked example, then problems that leave the last steps, then whole problems | measured, for novices; reversed for experts | error without the example; warning without the completion problem |
| practice brings earlier types back, in mixed order | measured in classroom trials, mostly mathematics; one year-long trial found no gain on the final test | warning |
Tested on material written before the shapes: 103 sections of 17 explained solution books and 1,197 notes of a study vault, with the predictions written before the count. The sections were worked examples, 101 of 103 with a trap, and none had objectives or a question block (what it found).
Status: the literature review is written and audited (2026-10-29): four multivocal reviews, 420 sources, in evidence; 304 lines checked against their sources, a second rater on every fifth grey source. Five shapes, their checks and an example of each are written; no shape has been tested on learners. It is an informal reading of published research and practice: not an official standard, not a peer-reviewed study, not a new result, and not a claim to the state of the art.
How it is made: with Claude, an AI assistant by Anthropic, under the maintainer's direction, the way reader-ergonomics was made. AI agents draft the literature reviews; every reference is resolved by script, and a number read only in a summary is marked "(secondary)". Corrections are welcome as issues.
Where it sits
It extends reader-ergonomics. The principles, their grades and the checks live there and are not repeated here. So do the learning effects themselves: retrieval, spacing, worked examples, multimedia. This repository adds what the genre changes: how each of these documents is built, and what a program can check in it.
Graphviz source
digraph levels {
graph [rankdir=TB, nodesep=0.6, 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"];
edge [fontname="Inter", fontsize=11, color="#3D434B", fontcolor="#55575F", penwidth=1.3, arrowsize=0.8];
L [label=<<font point-size="10" color="#55575F">LEVEL 2</font><br/><b>reader-ergonomics-learning</b><br/><font point-size="11" color="#55575F">the shapes of study documents, and their checks</font>>, fillcolor="#E8EEF8", color="#2F5DA8"];
T [label=<<font point-size="10" color="#55575F">LEVEL 1</font><br/><b>reader-ergonomics-topic</b><br/><font point-size="11" color="#55575F">one topic shape, nested to any depth, its check</font>>, fillcolor="#FFFFFF", color="#3D434B"];
R [label=<<font point-size="10" color="#55575F">LEVEL 0</font><br/><b>reader-ergonomics</b><br/><font point-size="11" color="#55575F">how any text serves its reader; learning science</font>>, fillcolor="#FFFFFF", color="#3D434B"];
L -> T [label=< derives its shapes from the topic,<br/> pinned v0.4.0>];
T -> R [label=< obeys the principles>];
L -> R [label=< obeys the principles; CI runs<br/> their checks here, pinned v1.18.2>, constraint=false];
}- It obeys reader-ergonomics and runs its checks, as every extension does (extending.md).
- Its shapes derive from the topic: a title, a summary that stands for the document, a body, its contents, and what it points to. A lesson or an exercise sheet adds its own blocks and removes none.
- No level depends on a level above it. Nothing below links up to this repository.
Why it exists
The evidence on how people learn is reviewed already. What is missing is the step from that evidence to the documents a learner studies, and a program that checks them.
| What exists | Where | What it leaves out |
|---|---|---|
| the learning effects, each with its grade and its effect size | reader-ergonomics, learning science | how a question, a card or an exercise sheet is written |
| guides in prose for teachers and authors | practice guides and books, placed by the reviews | a check a program can run |
| lesson templates checked by a program | The Carpentries Workbench | its checks read headings, blocks and links, not what the lesson teaches |
Scope
| What | Why | |
|---|---|---|
| in | written material studied alone: a lesson or chapter, a set of worked examples, an exercise sheet, a study guide, a deck of flashcards, and the questions inside them | the reader is the learner, and the document is the object, as in reader-ergonomics |
| in | material a teacher writes for others, and material learners write for themselves | both are read the same way, alone and again later |
| in | the shapes of these documents, and the checks a program can run on them | what a program can check, a program checks |
| out | whether a learning technique works | reviewed in reader-ergonomics, and linked from here |
| out | teaching live: lectures, talks, live coding | reader-ergonomics-presentations |
| out | the algorithms that schedule reviews | benchmarked in reader-ergonomics; a deck uses one, this repository does not build one |
| out | tutoring systems, platforms and AI tutors | software and dialogue, another object |
| out | exam design for grading and its statistics | another field; only the rules that also hold for a self-test question are in |
| out | programme and curriculum design | the unit here is a document, or the material of one course |
The four reviews
Each review asks how the document is written so that a technique reaches the learner, not whether the technique works. Each is a multivocal literature review: research and practice together, every grey source scored for quality.
| Review | Question | Sources |
|---|---|---|
| practice-questions | how the questions inside study material are written, placed and answered | 107 |
| flashcards | how prompts for spaced review are written, made and kept | 100 |
| exercise-sets | how a set of exercises is ordered and supported, from worked example to problem | 117 |
| instructional-text | how an explanatory text is built around its content: objectives, terms, summaries, boxes | 96 |
Why four, and where each work is reviewed: decision 0002.
What the reviews found
Each line links the review that holds its evidence; "(secondary)" marks a number read only in a summary.
| Document | What the evidence settles | Grade | What these searches did not find tested |
|---|---|---|---|
| practice questions | testing transfers to application and inference questions (d = 0.32); feedback with more information has larger effects; when feedback comes makes no average difference (g = 0.03, secondary) | measured | where the answers sit: folded, at the end of the chapter, at the back |
| flashcards | dropping a card once it is recalled lowers retention; one large stack beats several small ones; learner-made cards beat premade ones (d = 0.45, secondary), contested for vocabulary | measured; the last contested | one fact per card; fill-in-the-blank against question cards inside a spaced repetition app |
| exercise sets | mixing earlier types into homework raised delayed classroom scores (d = 0.79 at 30 days); fading the steps of worked examples beats example-problem pairs | measured, mostly mathematics | a whole sheet built from the measured parts; when to release solutions; hints on paper |
| instructional text | a text that states a misconception and refutes it beats plain exposition (g = 0.36 over 30 comparisons); guided notes raise college achievement (d = 0.55); open textbooks teach as much as commercial ones (g = 0.01) | measured | aligning objectives with the checks, in a controlled trial; revision guides |
Every review ends in proposals for the shapes and the checks, each with its grade (shapes-and-checks.md in each folder). The five shapes were written from them, and each block names the review it rests on.
The baselines the shapes must beat
| Document | Baseline | Also compared with |
|---|---|---|
| practice questions | a self-test of short-answer recall questions, the correct answer shown after each attempt | end-of-chapter questions as a textbook prints them |
| flashcards | a learner-made deck of question-and-answer cards in Anki, under its default scheduler | a ready-made shared deck of the same content |
| exercise sets | the blocked sheet: one run of same-type problems per lesson, answers at the end | the example-problem pair, for how a new type opens |
| instructional text | an open-textbook section: objectives, bold terms, a summary, checks with a key | a Carpentries episode, for a single lesson |
Each review's baseline.md gives the design of the comparison: matched time, a delayed test, transfer items.
Brought from the sibling repositories
Linked at a pinned commit, never copied (one place per fact).
| From | What | Used for |
|---|---|---|
| reader-ergonomics | the principles, the learning-science review, the checks, the stylesheet, the extension contract, the decision-record shape | every document here; decisions; CI |
| reader-ergonomics-topic | the topic, base of every shape, and its check; the review method its three reviews share | the shapes; CI; the four reviews |
| reader-ergonomics-software-design | the method for reading question-and-answer sites | the Q/A strand of each review |
| reader-ergonomics-presentations | teaching live, which stays there; contexts that override a base for one audience | the boundary; a model for the reading speeds of a study guide, to be tested |
Contents
| Part | Holds |
|---|---|
| shapes | the five shapes of study documents, each with the evidence behind its blocks, its checks and an example |
| decisions | one record per choice that shapes this repository, each opening with the decision in one sentence |
| evidence | the four reviews, 420 sources, and the bibliography of 452 works |
Next
- Read Rowland 2014 and Yang 2021, published by APA, to which the university has no subscription: their three rows are marked as not checked. The other two paywalled papers were read (audit).
- Test the shapes on learners, against the baseline each review names. The test on the explained solution books of University-Coursework was against written material, not learners.
Check it
git clone https://github.com/Tewf/reader-ergonomics && git -C reader-ergonomics checkout bfbe9f7 # the pinned release
python3 reader-ergonomics/checks/run.py path/to/this/repositoryCI 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-learning (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.