Ergonomie du lecteur

Comment écrire des notes, des documents et des fichiers qui coûtent le moins possible au lecteur, d'après ce que les sciences cognitives, la psycholinguistique et le génie logiciel ont mesuré. Pour les personnes qui écrivent, et pour les modèles de langue qui écrivent.

État : version 1.21.0, publiée le 2026-11-04.

  • Relu : par personne d'autre que son mainteneur, qui a lu et noté les preuves avec des agents d'IA. Ce n'est ni un standard officiel, ni une étude relue par des pairs, ni un résultat nouveau, ni une prétention à l'état de l'art.
  • Vérifié : par trois audits des affirmations face à leurs sources primaires, chacun par des agents qui n'avaient pas écrit les lignes vérifiées ; chaque ligne fausse est listée avec sa correction.
  • Noté : chaque principe dit la force de ses preuves, et beaucoup sont des conventions que personne n'a testées.
  • Corrections : bienvenues sous forme d'issues.

Comment il a été fait : avec Claude, un assistant d'IA d'Anthropic, sous la direction du mainteneur. Des agents d'IA ont rédigé les revues de littérature ; chaque référence a été résolue par un script et les affirmations ont été vérifiées par sondage, mais toutes les sources n'ont pas été lues en entier, et un chiffre lu seulement dans un résumé est marqué « (secondary) ».

Read in English

Par où commencer

Vous êtes Commencez par
quelqu'un qui écrit, ou un modèle sur le point d'écrire standard.md : une page, chaque principe avec son niveau de preuve, et comment vérifier son texte
un lecteur qui veut les raisons evidence/ : une revue de littérature par thème, avec les arguments contre chaque principe
quelqu'un qui écrit pour un lecteur connu reader-styles/ : ce qui change pour un novice, un expert, un lecteur visuel, un modèle de langue
quelqu'un qui étend le standard à un genre extending.md : la structure à reproduire, et les parties de ce dépôt sur lesquelles compter

Prendre sa propre version

Le standard est fait pour être copié et gardé. Pour en faire votre version :

  1. Forkez ou copiez ce dépôt, ou seulement standard.md, les formes que vous utilisez et checks/.
  2. Nommez votre lecteur : choisissez un style dans reader-styles/, ou écrivez-en un à partir du modèle.
  3. Épinglez une version par son commit, jamais une branche, pour qu'un changement ultérieur ici ne change pas ce que vous avez pris. Chaque version, avec son commit et ce qu'elle change, est dans le CHANGELOG ; un job de CI l'épingle comme le montre extending.md.
  4. Lancez les vérifications sur votre texte, avec la commande ci-dessous.

Un désaccord avec un principe a trois endroits où aller :

  • votre style de lecteur, comme une dérogation avec sa raison, s'il porte sur votre lecteur ;
  • une extension, s'il porte sur un genre ;
  • une issue ici, si les preuves sont fausses.

Contenu

Dossier Rôle
principles/ la meilleure hypothèse actuelle pour tout lecteur, un fichier par principe, rangé par échelle : collection, document, phrase, page
reader-styles/ les ajustements pour un lecteur connu, car ce qui marche le mieux dépend de qui lit
shapes/ des squelettes fixes par type de document : note, README de dossier, rapport, message de commit, fiche de décision
evidence/ les revues derrière les principes, et une bibliographie commune
checks/ des programmes qui vérifient ce qu'un programme peut vérifier ; des questions pour le jugement sinon
decisions/ pourquoi le dépôt est construit ainsi : une fiche par décision, avec les options écartées

Pourquoi des niveaux de preuve

Un principe ne vaut que ses preuves. Chacun indique s'il a été mesuré (measured), s'il est soutenu avec réserve (supported with caveat), s'il est une convention que personne n'a testée (convention), ou s'il a été testé sans résultat (not supported). Certaines règles connues tombent dans les deux derniers groupes, et le standard le dit.

Vérifier un dépôt

git clone https://github.com/Tewf/reader-ergonomics
python3 reader-ergonomics/checks/run.py chemin/vers/votre/depot

Seule la bibliothèque standard de Python est nécessaire. Les constats exacts font échouer l'exécution ; les questions qu'un programme ne peut pas trancher sont écrites dans checks/out/needs-judgment.md, et leurs réponses sont gardées dans checks/judgments.toml. Voir checks/.

Contribuer

AGENTS.md donne les règles pour modifier ce dépôt, pour les personnes comme pour les modèles.

Langue

Le contenu est en anglais ; seules les deux pages d'accueil sont bilingues.

Licence

Code sous licence Apache 2.0 ; textes sous CC BY 4.0. Réutilisez-les librement, en mentionnant ce dépôt ; CITATION.cff donne une citation si besoin.