Contributing to this repository

For anyone changing this repository, person or language model. To apply the reader-ergonomics standard elsewhere, read its standard.md; this file is about this repository only.

Before writing

  1. Read the standard at the release this repository checks against (v1.18.2), then its learning-science review, then the topic every shape here derives from.
  2. Ask of every new claim whether it is about the document or about the technique. A claim about whether a technique works belongs to the standard; here it is linked, with one line of context (decision 0001).
  3. A new file is listed by the README of its folder, with its summary. A new folder gets a README.md, listed by the README above it, and a one-line index.qmd that includes it, because the site generator skips README files.
  4. This repository has no principles of its own yet, so it has no standard.md card: the standard's card is the one to follow.

Rules for claims

  • Every claim carries a grade: measured, supported with caveat, convention or not supported. A grade moves only with a cited source.
  • Cite as Author Year; the entry goes once into evidence/bibliography.md, with a DOI, an arXiv id, an ERIC id or a stable URL. A key names one work across the six repositories of the family: check it against their bibliographies before adding it.
  • Evidence against a rule goes into the review's against.md, never deleted to make a rule look stronger.
  • A number read in a summary rather than in the source is marked "(secondary)".

Before handing back

Run the checks against the release CI uses, not a checkout that may have moved on. The first two lines unpack it into checks/out/standard, inside the checks/out/ that git ignores, as reader-ergonomics extending.md (Versions) gives it; emptied first, so a new pin leaves no file of the old release behind.

rm -rf checks/out/standard && mkdir -p checks/out/standard
git -C ../reader-ergonomics archive bfbe9f7 | tar -x -C checks/out/standard   # the pinned release
git -C ../reader-ergonomics-topic show 1220def:checks/local/topic.py > checks/local/topic.py   # as CI does; never committed
python3 checks/out/standard/checks/run.py . --tiers program,meaning --judge flag   # the repository, as CI runs it
READER_ERGONOMICS_CHECKS=checks/out/standard/checks python3 -m unittest discover -s checks   # the checks of the shapes
  • Fix every error. Read every warning.
  • A key names one work across the family: bibliography-keys compares evidence/bibliography.md with each repository its config names, cloned beside this one as CI does; a sibling not found is a warning, never a pass.
  • Answer the questions in checks/out/needs-judgment.md in checks/judgments.toml. A model does not review its own text in place of the checks; its answers are advice until the maintainer has read them.
  • Keep llms.txt in step when a page is added, moved or removed: nothing generates it.
  • Keep README.md and README.fr.md in step.

House conventions

  • No em dash or en dash in prose; use a comma, a colon, parentheses, or a hyphen for ranges.
  • Commit messages follow the standard's commit shape: a subject of at most 72 characters, then why.
  • A choice that shapes the repository gets a record in decisions/.
  • The maintainer decides every push.