The reader-ergonomics standard

The principles below are the best current guess for a reader nobody knows, as far as the evidence goes. When the reader is known, their reader style overrides what it names, and everything else here still holds.

How to use it

Ask who reads and open their reader style if known; pick the shape; write to the principles; run the checks, whose three kinds of finding the steps below define.

Graphviz source

digraph how_to_use {
  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];
  Q [label=<<b>who reads?</b>>, fillcolor="#FFFFFF", color="#3D434B", shape=diamond, style="filled", margin="0.05,0.05"];
  STY [label=<<b>open their reader style</b>>, fillcolor="#E6F2EA", color="#2E7D4F"];
  SH [label=<<b>pick the shape</b>>, fillcolor="#FFFFFF", color="#3D434B"];
  PR [label=<<b>write to the principles</b>>, fillcolor="#FFFFFF", color="#3D434B"];
  RUN [label=<<b>python3 checks/run.py .</b>>, fillcolor="#FFFFFF", color="#3D434B"];
  Q -> STY [label=" known"];
  Q -> SH [label=" unknown"];
  STY -> SH;
  SH -> PR;
  PR -> RUN;
  E [label=<<b>error</b><br/><font point-size="11" color="#55575F">certain: fix it</font>>, fillcolor="#FBEDE4", color="#B4541A"];
  W [label=<<b>warning</b><br/><font point-size="11" color="#55575F">fix it, or say why it is false</font>>, fillcolor="#FBEDE4", color="#B4541A", style="rounded,filled,dashed"];
  J [label=<<b>judgment</b><br/><font point-size="11" color="#55575F">answer it in checks/judgments.toml</font>>, fillcolor="#E8EEF8", color="#2F5DA8"];
  RUN -> E;
  RUN -> W;
  RUN -> J;
  {rank=same; E; W; J}
}

Name the reader. If they are known, open their style in reader-styles/.
Pick the shape of the document from shapes/.
Write to the principles below; each file says what it asks, why, and where it stops.
Check: python3 checks/run.py . (or the path to this repository's checks/run.py, followed by the folder to check).
- Fix every error: it is certain.
- Fix every warning, or say in one line why it is a false match: warnings come from heuristics.
- Answer the judgment questions in checks/out/needs-judgment.md, written only when there are questions, for whoever is at work; none is a normal result for a short text. An answer goes in checks/judgments.toml, committed with the text, and holds until its file changes. It quotes, in backticks, what in the file its reason rests on; judgment-quotes fails an answer whose quotes the file does not hold. The open questions come ready to fill in, in checks/out/judgments-to-answer.toml.
- A program verifies what a program can; judgment answers the rest; nobody reviews their own text in place of the checks.

Grades

Every principle says how strong its evidence is, and never claims more. When the clauses of a claim rest on evidence of different strength, the grade names each clause with its own grade.

measured: controlled studies or meta-analyses found the effect.
supported with caveat: evidence exists, with a limit the principle states.
convention: agreed or standardised, not tested.
not supported: tested, and the effect was not found.

Principles

The principles act at four scales; the first three nest, the fourth is how all of them are shown.

Three nested scales: the collection holds documents, a document holds sentences; the page is how all three are shown.

Graphviz source

digraph scales {
  graph [rankdir=TB, nodesep=0.4, ranksep=0.5, bgcolor="white", pad=0.2, fontname="Inter", compound=true];
  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];
  subgraph cluster_collection {
    label=<<b>collection: folders and files</b><br/><font point-size="11" color="#55575F">what the reader navigates</font>>; labeljust=l;
    style="rounded,filled"; fillcolor="#E8EEF8"; color="#2F5DA8"; fontname="Inter"; fontsize=13; margin=14;
    subgraph cluster_document {
      label=<<b>document: one file</b><br/><font point-size="11" color="#55575F">the order and depth the reader follows</font>>; labeljust=l;
      style="rounded,filled"; fillcolor="#E6F2EA"; color="#2E7D4F"; fontname="Inter"; fontsize=13; margin=14;
      subgraph cluster_sentence {
        label=<<b>sentence</b>>; labeljust=l; style="rounded,filled"; fillcolor="#FBEDE4"; color="#B4541A"; fontname="Inter"; fontsize=13; margin=12;
        S [shape=plaintext, style="", label=<<font point-size="11" color="#55575F">what the reader holds in memory</font>>];
      }
    }
  }
  PG [label=<<b>page</b><br/><font point-size="11" color="#55575F">how all three are shown: figures, signals, type</font>>, fillcolor="#FFFFFF", color="#3D434B", style="rounded,filled,dashed"];
  S -> PG [ltail=cluster_collection, dir=back, style=dashed, color="#6A6D77", label=" shows all three"];
}

Collection: files and folders

Principle	Claim	Grade
Browsable folders	a collection is shallow and broad: two levels rather than three, and folders a reader can scan, of at least 3 and at most about 32 entries.	supported with caveat for two levels rather than three and up to about 32 entries; the evidence is from menus and web pages, applied to folders by analogy. The floor of 3 entries is a convention, argued from the cost of depth
Dependencies without cycles	code dependencies between folders never form a cycle, so every folder sits on a level above everything it uses.	convention, argued from design practice
Group by what changes together	a folder holds what serves one purpose and changes together, not files of one type; other ways of grouping are carried by links and indexes.	supported with caveat for grouping what changes together; that it beats grouping by type is untested, with no controlled comparison; indexes for the other groupings are a convention, from library science
Names predict content	a reader can predict what a file, folder or heading holds from its name before opening it, and each thing has one name throughout.	supported with caveat for names that predict content; one name per thing argued from theory for people and supported with caveat for language models
One place per fact	each piece of knowledge that must change together lives in one file; every other place links to it.	supported with caveat
One role per file	a file holds one role: what it does fits one sentence, and its parts change for the same reasons.	convention, untested
Portable paths	every path in a repository can be checked out on any common filesystem.	convention (a platform specification)
Size is a prompt	past a length, a file is asked to state its role; size alone never decides a split.	convention, untested. The belief that smaller files have fewer defects is not supported
Tunables in config	a value someone will set (a quota, a threshold, a price) lives in a configuration file, read at run time, and a value nobody has measured yet is tagged PROVISIONAL.	supported with caveat for one place for a value that will change, from information hiding; the PROVISIONAL tag is a convention: tagged shortcuts are measured as common and often left, not as helpful

Document: order and depth

Principle	Claim	Grade
Define before use	every term and symbol is defined at or before its first use, premises come in the order they are needed, and each thing keeps one name.	supported with caveat for a definition before its use. Premises in the order they are needed: measured for language models, argued from theory for people. One name per thing: argued from theory for people, supported with caveat for language models
One mode per document	each document serves one mode of reading (learning by doing, doing a task, looking something up, or understanding why) and says which.	convention, untested; widely adopted
Overview first	a document opens with what it is about and how it is organised (its parts, in a few lines or a simple map) before any detail.	measured
Retrieval prompts	a document meant to be learned ends each part with a few questions the reader answers from memory, with the answers folded, and is reread after a gap.	measured for questions answered from memory and for spaced rereading; folding the answers supported with caveat, inferred from the testing effect and not tested as a layout
Shallow outline	what matters most sits at the top of a document's hierarchy, and the outline stays shallow: at most three levels of headings.	measured for recall of top-level ideas; the three-level limit is a convention
Short reference distance	each concept sits close to the places that use it, and the order of a document is chosen so that prerequisites come first and the total distance between definitions and uses is small.	supported with caveat: locality is measured in sentences and applied to documents by analogy
Worked examples with subgoals	a method is taught by a solved example whose steps are named by what they achieve, then faded: the next examples leave more steps to the reader.	measured, for novices; reversed for experts

Sentence: density, locality and nesting

Principle	Claim	Grade
Even information density	a text says no more than the reader needs, and spreads what it says: no sentence packs several new ideas, and a dense term arrives after its context.	supported with caveat for judged quality; not supported as a way to read faster
Given before new	a sentence starts from what the reader already has (the topic, or what the previous sentence ended on) and ends on what is new.	supported with caveat
Shallow nesting	a sentence puts at most one clause inside another; with two nested clauses, readers already misread.	measured in English, where readers misread at two nested clauses; not found in German, so the limit of one is a convention there
Short dependencies	words that depend on each other stay close: a subject near its verb, a modifier next to what it modifies, a pronoun near what it refers to.	measured in controlled sentences; supported with caveat in natural reading; a pronoun near what it refers to is applied by extension

Page: figures, layout and type

Principle	Claim	Grade
Draw relations	a relation, a set, a quantity or a process is shown as a figure placed with the words that explain it, not as words alone.	measured
Figure next to its text	the words that explain a figure, a formula or a block of code sit beside or inside it: not on another page, not below the fold.	measured for figures and formulae, in learning material for novices; for code, applied by analogy
Readable measure	body text has a line length of about 45 to 75 characters, a size in the fluent range, and line spacing of at least 1.5.	measured for a size in the fluent range. A line of 45 to 75 characters: supported with caveat, best for understanding and preference but not for speed. Line spacing of at least 1.5: a convention
Signal the structure	the structure of a text is visible before it is read: headings that name their content, lists for parallel items, tables for comparisons, bold for the defined term.	measured for signals (headings, labels, cues); tables for comparisons supported with caveat, from cognitive fit; lists for parallel items and bold for the defined term are conventions
Sufficient contrast	text has a contrast ratio of at least 4.5:1 against its background, dark text on a light ground by default, with a dark theme offered and never forced.	measured for dark text on a light ground; the 4.5:1 floor is a convention (a standard), and so is an offered dark theme

When two principles pull apart

The stronger grade wins. At equal grade, the reader style decides; with no style, the reader with less prior knowledge does.
One place per fact makes the reader follow links, and every link is a hop. Link, and give a novice a one-line reminder at the distant use.
Lifting shared files to a common ancestor crowds it. Put shared code in a folder of its own, declared as a lower level.
A file past the size trigger that passes the one-role test stays whole.

Where the evidence is

Every principle links to its review in evidence/, and every work cited is listed once in the bibliography.