Topic
Un seul gabarit pour une unité d'écriture, appelée topic, dont les parties peuvent être des topics du même gabarit. Tout ensemble d'informations s'écrit alors comme un arbre qui se lit de la même façon à chaque profondeur.
Le nom est celui du domaine. Un topic est l'unité de DITA et de la rédaction modulaire (topic-based authoring) (information typing). Les modèles de documents appellent la même unité un objet de contenu (document model), et les études des arbres à l'écran l'appellent un nœud (progressive disclosure).
Cette page en anglais : README.md. Les deux versions suivent le même état.
État : un gabarit, le topic ; sa vérification ; et trois revues multivocales de 218 sources, faites le 2026-10-29, dans evidence. Aucune étude auprès de lecteurs n'a testé le gabarit. Son gain sur le topic de base de DITA est posé comme un test à quatre issues (baseline), dont aucune n'a encore été menée. Le volet augmenté par l'IA, sur la vérification d'un raisonnement écrit en topics, est parti le même jour pour un dépôt à lui (0016). Ce n'est ni une norme officielle, ni une étude évaluée par des pairs, ni un résultat nouveau.
Comment il est fait : avec Claude, un assistant IA d'Anthropic, sous la direction du mainteneur, comme reader-ergonomics. Les corrections sont bienvenues sous forme d'issues.
Le prendre
Le topic est fait pour être copié et gardé comme le vôtre. Copiez-le depuis une version étiquetée (tags) : un changement ici ne change jamais votre copie.
Copiez shapes/topic.md, la forme, et checks/local/topic.py, la vérification, aux mêmes chemins dans votre dépôt.
Écrivez vos topics : chacun un fichier avec un titre et un résumé, le README de chaque dossier listant ses enfants avec les leurs.
Ajoutez
checks/config.toml; les deux dernières tables valent pour un dépôt sans feuille de style de site :extends = "reader-ergonomics" [topic] files = ["README.md", "docs/"] # vos topics : fichiers et dossiers root = "README.md" [readable_measure] stylesheets = [] [sufficient_contrast] stylesheets = []Lancez les vérifications de la norme au commit que la version épingle (
ref:dans son checks.yml) ; celle du topic tourne à côté :git clone https://github.com/Tewf/reader-ergonomics git -C reader-ergonomics checkout <le commit épinglé> python3 reader-ergonomics/checks/run.py chemin/vers/votre/dépôtComment prendre votre propre version de la famille, et où va un désaccord : la section Take your own version de la norme.
Où il se place
Source Graphviz
digraph where_it_sits {
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];
LE [label=<<b>reader-ergonomics-learning</b><br/><font point-size="11" color="#55575F">niveau 2</font>>, fillcolor="#E6F2EA", color="#2E7D4F"];
OT [label=<<b>reader-ergonomics-academic, -presentations,</b><br/><font point-size="11" color="#55575F">-software-design, autres projets</font><br/><font point-size="11" color="#55575F">niveau 2</font>>, fillcolor="#E6F2EA", color="#2E7D4F", style="rounded,filled,dashed"];
TO [label=<<b>reader-ergonomics-topic</b><br/><font point-size="11" color="#55575F">une forme de topic, imbriquée à toute</font><br/><font point-size="11" color="#55575F">profondeur, sa revue et sa vérification</font><br/><font point-size="11" color="#55575F">niveau 1</font>>, fillcolor="#FBEDE4", color="#B4541A", penwidth=2.6];
RE [label=<<b>reader-ergonomics</b><br/><font point-size="11" color="#55575F">comment un texte sert son lecteur</font><br/><font point-size="11" color="#55575F">niveau 0</font>>, fillcolor="#E8EEF8", color="#2F5DA8"];
LE -> TO [label=" épingle une version ; ses formes\l dériveront du topic\l"];
OT -> TO [style=dashed, color="#6A6D77", label=" peuvent prendre le topic pour\l squelette (une hypothèse)\l"];
TO -> RE [label=" obéit aux principes ; la CI\l exécute leurs vérifications ici\l"];
{rank=same; LE; OT}
}- Il obéit à reader-ergonomics, donc il se place un niveau au-dessus, et un projet qui l'utilise se place au-dessus de lui. Aucun niveau ne dépend d'un niveau supérieur.
- reader-ergonomics ne pointe jamais vers lui : la norme ne pointe vers aucune extension. Ce dépôt pointe vers la norme, jamais vers les extensions.
- Une extension dit qu'elle l'utilisera : reader-ergonomics-learning épingle une version et écrit que ses formes dériveront du topic ; aucune n'est encore écrite. Que les autres l'utilisent est une hypothèse. Si aucune ne le fait, ce dépôt répond quand même à une question.
Périmètre
| Quoi | Pourquoi | |
|---|---|---|
| dedans | les preuves sur les gabarits récursifs, du côté du lecteur | le lecteur est l'objet, comme dans reader-ergonomics |
| dedans | la forme du topic : les blocs de tout topic, et comment un topic contient d'autres topics ou pointe vers eux | un seul gabarit, gardé en un seul endroit |
| dedans | une vérification qu'un programme exécute sur un topic à toute profondeur | ce qu'un programme peut vérifier, un programme le vérifie |
| dehors | les genres : articles, preuves, exposés, documents de conception | ils restent dans leurs propres dépôts |
| dehors | ce qu'est une affirmation de recherche, comment on la prouve ou la vérifie | un autre problème, avec ses propres preuves ; le volet qui s'en chargeait est parti pour un dépôt voisin (0016) |
Ce que la revue a trouvé
Chaque réponse renvoie à la revue qui porte ses preuves ; un niveau dit la force de ces preuves.
| Question | Réponse | Niveau | Revue |
|---|---|---|---|
| Profondeur. Les lecteurs retiennent mieux les niveaux du haut, et reader-ergonomics limite un plan à trois niveaux. La récursion peut-elle être illimitée dans le stockage et plafonnée dans ce que voit le lecteur ? | Oui, comme conception, à trois conditions : le chemin vers la racine est montré, ce dont la plupart des lecteurs ont besoin se trouve avant le premier pli, et chaque topic replié montre un résumé. Les lecteurs ouvrent rarement une seconde couche, et pour des agents un second niveau de pliage n'a jamais aidé. | supporté avec réserve ; jamais testé directement | progressive-disclosure |
| Autoréférence. Un type de topic dont les enfants sont des topics donne un arbre ; un topic qui se contient lui-même est un cycle. Lequel faut-il au gabarit ? | Le type récursif seul. Chaque modèle de document lu garde chaque instance comme un arbre fini, et interdit, signale ou plafonne un cycle, ou le laisse indéfini. | convention, sur 14 systèmes | document-model |
| Graphes. Un topic utilisé par deux parents ne forme plus un arbre. L'arbre n'est-il que le stockage, et le graphe le sens ? | Les normes stockent un graphe d'arbres et donnent à chaque lecture un seul arbre : un parent qui contient, tout autre parent par référence. Aucune étude de la façon dont les lecteurs rencontrent une unité réutilisée n'a été trouvée. | convention ; le côté lecteur est une lacune | document-model |
| Genres. Le topic est-il ce que partagent les formes de genre, ou leur rival ? | Ce qu'elles partagent, comme la pratique le fait déjà : DITA dérive concept, tâche et référence d'un même topic de base. Le typage seul n'a donné aucun gain d'apprentissage dans le propre test de Horn en 1969 (19,56 contre 17,65, 41 étudiants). Qu'un lecteur qui connaît la base lise mieux un type dérivé n'a pas été testé. | convention ; ce transfert est la question ouverte de ce dépôt | information-typing |
La référence que le topic doit battre
| Lecteur | Référence | Contrôle |
|---|---|---|
| une personne, l'unité et ses types | le topic de base de DITA 1.3 avec ses types concept, tâche et référence, ses maps et sa réutilisation par référence, validé, cycles signalés | le même contenu en prose non typée |
| une personne, l'arbre sur une page | le même contenu en un seul document d'au plus trois niveaux de titres, sa table des matières toujours visible à côté | l'arbre entièrement déplié |
| un modèle | des passages retrouvés dans l'ordre du document, à budget de jetons égal | un arbre de résumés |
La comparaison mesure le repérage, l'idée générale contre le détail, le rappel après un délai, le transfert vers un type dérivé jamais vu, et ce qu'une vérification par programme attrape. Le fichier baseline.md de chaque revue en donne le plan.
Le gabarit du topic
| Partie | Résumé |
|---|---|
| shapes | le topic, la base dont dérive toute forme, et comment les quatre formes générales de reader-ergonomics s'y ajustent |
| la vérification | s'exécute sur chaque topic de ce dépôt, à toute profondeur : titre, résumé, listé par son parent avec ce résumé, aucun cycle d'inclusion |
| decisions | un compte rendu par choix d'architecture, chacun ouvert par la décision en une phrase |
- Le topic a cinq blocs : titre, résumé, corps, contenu et voir aussi. Chacun est relié à un principe de reader-ergonomics et aux preuves d'ici (topic).
- Les quatre formes générales s'ajustent toutes, avec deux renommages et une fusion : la ligne de sujet d'un commit est à la fois son titre et son résumé. Le topic a été tiré de ces quatre formes, donc le test le plus juste est le suivant (le tableau).
- Sur six formes des extensions de genre dont il n'a pas été tiré, cinq s'ajustent ; un compte rendu de décision sans résumé ne s'ajuste pas. Exécutée sur ces trois dépôts, 113 documents, la vérification trouve 7 défauts une fois leurs étapes de revue déclarées comme types, dans la configuration de ce test.
- Le compte rendu de décision, écrit d'abord ici, vit maintenant dans reader-ergonomics (v1.3.0). Les comptes rendus de ce dépôt le suivent, et la vérification contrôle que chacun le déclare.
- Ce dépôt est son propre premier arbre de topics : la vérification s'y exécute en CI, et ses tests sont dans checks/test_topic.py.
Suite
- Comparer le topic à la référence ci-dessus, auprès de lecteurs : le plan est dans le
baseline.mdde chaque revue. - Les extensions de genre peuvent dériver leurs formes du topic ; chacune le dirait dans son propre dépôt.
Le vérifier
git clone https://github.com/Tewf/reader-ergonomics
python3 reader-ergonomics/checks/run.py chemin/vers/ce/depotLa CI exécute les mêmes vérifications à chaque push, et une exécution échoue sur toute erreur (checks.yml). Chaque push sur master produit aussi le site, tewf.github.io/reader-ergonomics-topic (pages.yml).
Licence
Code sous Apache License 2.0 ; prose sous CC BY 4.0. Réutilisez-le librement, en citant ce dépôt ; CITATION.cff donne une citation si besoin.