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 shapes/topic.md.
  2. Every document here is a topic: a title, a summary right after it, and a line in its parent that lists it with that summary. A new file is listed by the README of its folder. 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.
  3. This repository has no principles of its own, 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 or a stable URL. A key names one work across the family (reader-ergonomics decision 0003): the family is listed under [bibliography_keys] in checks/config.toml, and CI checks every key against its bibliographies.
  • 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 them against the release CI uses, not a checkout that may have moved on. Extract it inside this repository, in checks/out/standard, which git and the checks both skip (reader-ergonomics extending.md, Versions):

rm -rf checks/out/standard && mkdir -p checks/out/standard
git -C ../reader-ergonomics archive bfbe9f7 | tar -x -C checks/out/standard   # the commit checks.yml pins
READER_ERGONOMICS_CHECKS=checks/out/standard/checks python3 -m unittest discover -s checks   # the topic check's tests
python3 checks/out/standard/checks/run.py . --tiers program,meaning --judge flag            # the repository, as CI runs it
  • Fix every error. Read every warning.
  • 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.
  • Each answer about a file's content is written after reading the file, and quotes in backticks a word or heading of it. The standard's judgment-quotes check fails an answer whose quote is not in its file. A reason then cannot be copied from another file's answer unread.
  • Keep llms.txt in step when a topic 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.