Copy page

Audit de la documentation

Lisibilité et structure du dossier

En bref :

• La forme de base tient : chaque page a une description et un « En bref », aucune n'a de H1 ni de saut de niveau de titre, tous les liens internes aboutissent, et pnpm run check lance les garde-fous du dossier.
• La lecture rapide et la structure desservent la décision : sur 60 pages, l'« En bref » s'affiche en un seul paragraphe ; l'avis, l'échelle de preuve et le glossaire servent tout le dossier mais restent rangés dans une section ; l'analyse LPI pèse le quart de la section CRISalid.
• Le vocabulaire flotte : le registre des questions porte cinq noms, les deux parties n'ont pas leur numéro dans la navigation, les briques de CRISalid ont deux séries de noms et le POC deux noms.

Ce qui tient

Ce qui reste à reprendre

Priorité 1 : la lecture rapide et la structure

1. Les « En bref » écrits en lignes simples s'affichent en un seul paragraphe (60 pages).

Le README demande un bloc de trois lignes (Règles éditoriales). 60 pages l'écrivent en lignes simples, sans puce ni retour forcé (dont 30 en trois lignes, les autres en une, deux ou quatre) ; 24 l'écrivent en liste à puces. En Markdown, des lignes consécutives d'une même citation forment un seul paragraphe. Le HTML construit le confirme : dans dist/03-crisalid/02-sous-projets/carte-des-sous-projets.html, « En bref : », la première ligne et la deuxième (carte-des-sous-projets.mdx:9-11) tiennent dans un seul <p>. Les pages à puces (par exemple index.mdx:11-14, 00-avis-go-no-go.mdx:6-9) s'affichent bien en lignes distinctes. Le lecteur pressé, à qui ce bloc est destiné, trouve sur la majorité des pages un paragraphe compact au lieu de trois constats.

2. Trois pages qui servent tout le dossier sont rangées dans une section.

• L'avis d'ensemble porte les trois verdicts : NO-GO sur Projects, GO conditionnel sur CRISalid, PIVOT vers la vitrine (00-avis-go-no-go.mdx:15-17). Il se trouve pourtant au quatrième niveau de la navigation : Compréhension LPI › Audit technique & arbitrage › Arbitrage, après les six pages thématiques. Sa description le présente comme « Synthèse de l'audit LPI » (ligne 4).
• L'échelle de preuve se dit « commune à tout le dossier » (sources-et-preuves.md:8). Elle est rangée en dernier dans CRISalid › Repères (scripts/generate-navigation.mjs:241, rang 50). Sa description parle d'« échelle des statuts de la section CRISalid » (ligne 4).
• Le glossaire se décrit comme valable « dans le reste de l'audit » (glossaire.md:4), mais son « En bref » le limite aux « termes de la section » (ligne 7). Il ne définit ni GO conditionnel, ni PIVOT, ni Projects, ni POC de pertinence, ni Partie 1 et 2, ni DiBISO : la seule entrée de décision est « Go / No-Go » (ligne 98). L'accueil n'y renvoie pas.

3. L'analyse LPI reste la section décisionnelle la plus mince.

Comptes en mots, hors front matter, imports, schémas Mermaid et blocs de code, tableaux compris :

Aucune page ne décrit les données de Projects (modèle, export, identifiants, réversibilité). Ce critère pèse pourtant 15 % dans la grille d'arbitrage (ligne 31). La section qui porte le NO-GO pèse ainsi le quart de CRISalid et le tiers de la veille.

4. La section « Audit de la documentation » sert de source de contenu.

Cette section juge le dossier ; plusieurs pages de contenu s'appuient pourtant sur elle comme sur une page qui fait foi :

• Scénarios et coûts renvoie à Les sous-projets en clair comme « inventaire » des briques (ligne 74), et non à la carte des briques, qui fait foi. La page 07 le reconnaît elle-même : « Scénarios et coûts renvoie encore ici comme « inventaire » au lieu de la carte » (07-sous-projets-en-clair.mdx:11).
• Le catalogue des présentations renvoie au livrable final pour décrire la restitution (ligne 8), et quatre decks le citent en source (par exemple 03-architecture-crisalid/deck.md:33).
• L'avis Go / No-Go renvoie aux limites de l'audit pour le détail de ses limites (ligne 81).

Le lecteur qui suit ces liens sort du parcours de décision pour entrer dans une section de relecture.

Priorité 2 : la forme et le vocabulaire

5. 30 pages n'ont pas l'« En bref » de trois lignes que demande le README. Aucun script ne le contrôle : check-dossier.mjs ne vérifie que la description, le registre et les motifs interdits.

• Une seule ligne sur les huit contrôles de 04-tutoriels/02-preuves/ (par exemple preparer-ikg.md:6-7).
• Deux lignes sur 19 pages :
  • six pages de veille (00, 02, 05, 06, 07, 08) ;
  • stockages-et-schemas.mdx ;
  • la carte des briques et ses cinq fiches ;
  • 00-par-ou-commencer.mdx et les quatre étapes du parcours ;
  • 07-sous-projets-en-clair.mdx, dans cette section.
• Quatre lignes sur trois pages : 05-deck/catalogue.mdx:7-11, et deux pages de cette section (04-presentations.mdx, 09-audit-des-presentations.mdx).
• Sur l'accueil, le bloc arrive en ligne 11, après une ligne en italique et un paragraphe (index.mdx:7-11).
• Certaines lignes dépassent 60 mots : scenarios-de-besoin.mdx:10 (69 mots), 03-portails-universitaires.mdx:8 (66), 00-panorama.mdx:8 (65), 02-plateformes-nationales.mdx:8 (63), ainsi que cinq pages de cette section (04-presentations.mdx, 05-limites-de-laudit.mdx, 07-sous-projets-en-clair.mdx, 08-section-crisalid.mdx, 09-audit-des-presentations.mdx).

6. Le registre des questions porte cinq noms.

« Grille d'évaluation » se confond avec la grille d'arbitrage, qui est une autre page. Le registre vise aussi la DiBISO et la DSI (Q19 à Q23), ce que « Questions à LPI » masque.

7. Les deux parties ne portent pas leur numéro dans la navigation.

Tout le dossier parle de « Partie 1 » et « Partie 2 » (accueil, index.mdx:20-22 ; titres des deux pages, « Partie 1 — Vitrine synchronisée en marque blanche » et « Partie 2 — Contribution des chercheurs »). La navigation les nomme « Vitrine en marque blanche » et « Contribution des chercheurs » (sidebar_label, et scripts/generate-navigation.mjs:136-137), dans une catégorie « Détail des deux parties » (ligne 132). Entre les deux s'intercale « Extrait et comparatif du POC » (rangs 20, 25, 30, lignes 296-298). Le lecteur qui cherche « Partie 2 » dans le menu ne la trouve pas sous ce nom.

8. Les liens de l'accueil ne portent pas le nom de la page qu'ils ouvrent.

Le tableau « Par où commencer » n'a pas non plus de ligne pour l'équipe CRISalid de la DiBISO, alors que deux des cinq décisions demandées la visent (index.mdx:33,36) et que le registre lui adresse ses questions.

9. Les briques de CRISalid ont deux séries de noms.

• Fiches : nommées par leur fonction, « L'annuaire », « Le moissonneur », « Le graphe », « L'API » (front matter de 02-sous-projets/coeur/).
• Contrôles : quatre sont nommés par leur dépôt, « Directory Bridge : entrées CSV », « IKG sans lancer les services », « Apollo : schéma et accès », « Champs transmis Bridge → IKG » ; deux par leur fonction, « Moissonneur et adaptateurs », « SoVisu+ sans la pile ».
• Glossaire : il ne connaît que les noms de dépôt, dont « SoVisuPlus (SVP) » et « SVP Harvester » (glossaire.md:54,57).
• SoVisu+ : écrit « SoVisuPlus » hors des noms de fichier et de dépôt, par exemple stockages-et-schemas.mdx:38 et dictionnaire-de-donnees.md:96.
• Navigation : la catégorie « Briques de CRISalid » (scripts/generate-navigation.mjs:70) contient une page « Les briques de CRISalid », soit le même libellé deux fois. Même redite dans la veille : la catégorie et la page « Panorama » s'intitulent toutes deux « Veille : plateformes existantes » (ligne 133 ; 00-panorama.mdx:2).
• Le mot « brique » désigne cinq composants dans carte-des-sous-projets.mdx:10, mais les 21 dépôts dans scenarios-de-besoin.mdx:74.

10. L'échelle de preuve n'est pas encore le seul vocabulaire.

• « non évalué » sert de statut sans figurer parmi les huit de l'échelle : index.mdx:7, 02-grille-arbitrage.mdx:24,40, 00-ce-que-linstance-demontre.mdx:150. Le README en fait pourtant la règle (« Une affirmation non démontrée est "non évaluée" », ligne 39).
• « À confirmer » n'a pas la même définition partout. Dans l'échelle commune, il s'agit d'une « Information absente des sources accessibles » (sources-et-preuves.md:23). Dans la méthode LPI, le statut couvre aussi « aucun mécanisme trouvé » et l'hypothèse qui attend une mesure (00-perimetre-principes.mdx:27). La phrase qui suit le tableau affirme pourtant que « ces mentions sont celles de l'échelle commune » (ligne 29).
• « à confirmer » en minuscules revient 99 fois, dont 57 en gras, comme un statut. Le gras est concentré dans la veille : 17 occurrences dans 02-plateformes-nationales.mdx, 9 dans 04-agregateurs-internationaux.mdx. Les 42 autres sont de la prudence de prose. Le lecteur ne peut pas distinguer les deux usages.

11. Le POC porte deux noms. On trouve « POC de pertinence » 47 fois et « POC de novembre » 10 fois, dans neuf fichiers : le point d'entrée des tutoriels, les quatre étapes du parcours et les quatre plans de tests (par exemple 00-par-ou-commencer.mdx:4,10, 00-plan-tests-seo.mdx:8). Or le POC court du 9 novembre au 4 décembre 2026 : « de novembre » est inexact.

12. Une préconisation n'est pas marquée dans l'analyse LPI. « ## Stratégie de rendu cible » (03-seo-rendu.mdx:37) prescrit le rendu de la future vitrine, sans statut. L'échelle range ce type de contenu en Projection Saclay (sources-et-preuves.md:25), comme l'architecture recommandée (01-stack-architecture.mdx:59-61).

Priorité 3 : l'ordre et l'équilibre

13. Les préfixes numériques ne suivent pas l'ordre de lecture, et ils figurent dans les URL :

• 03-crisalid/ se lit dans l'ordre 00, 06, 02, 01, 03, 04 (rangs de scripts/generate-navigation.mjs:227-236) ;
• 02-scenarios/ se lit 00, 01, 03, 02, 04 (lignes 295-301) ;
• 03-veille/ se lit 00, 08, 01, 02, puis les annexes 03 à 07 (lignes 214-222) ;
• 02-analyse-lpi/ passe de 00 à 02, et 01-cadrage-saclay/ de la racine à 02.

La méthode d'estimation, marquée « Annexe · », arrive en tête de sa section (rang 10, ligne 295) au lieu d'en fin. Renuméroter impose des redirections.

14. La veille reste trois fois plus longue que l'analyse qu'elle éclaire. Ses neuf pages font 21 133 mots, contre 7 310 pour toute l'analyse LPI. Le panorama, première page de la veille dans le parcours, est la plus longue du site (3 517 mots). Les cinq annexes (10 545 mots) pèsent autant que les quatre pages du parcours (10 588). Chaque plateforme y a son titre de niveau 2 : 30 dans 04-agregateurs-internationaux.mdx, 22 dans 02-plateformes-nationales.mdx. Il n'existe pas de tableau d'une ligne par plateforme.

15. L'audit de la documentation se répète. Ses 11 pages comptent deux pages sur les présentations (Les présentations, Audit des présentations) et deux sur CRISalid (Les sous-projets en clair, Audit de la section CRISalid).

16. Les libellés de navigation ne suivent pas une même forme.

• Casse : « Le Besoin Saclay » et « Prochaines Étapes » (scripts/generate-navigation.mjs:19,23) s'écartent de « Compréhension LPI » et « Audit de la documentation ».
• « & » ou « et » : « Sources & preuves », « Exploitation & pilotage », « Provenance, qualité & fusion » côtoient « Exploitation et gouvernance » et « Sécurité, droits et données personnelles ».
• Script : trois clés de rang sont déclarées deux fois, comprendre-crisalid.mdx (lignes 223 et 237), sources-et-preuves.md (224 et 241) et catalogue.mdx (225 et 277). Seule la dernière valeur compte.

17. Le site se déclare en anglais. Le HTML construit porte <html lang="en"> (dist/index.html) et l'index de recherche est construit pour l'anglais (dist/pagefind/pagefind-entry.json : "languages":{"en":…}). Un lecteur d'écran lit alors le texte français avec une prononciation anglaise, et la recherche n'applique pas la racinisation du français. Un ancien index de recherche de 8 pages est par ailleurs versionné dans docs/public/pagefind/ ; s'il est servi à la place de celui du build, cela n'a pas été vérifié.

Recommandations, dans l'ordre

1. Écrire les « En bref » en liste à puces, comme les 24 pages qui s'affichent déjà en trois lignes, et ajouter à scripts/check-dossier.mjs le contrôle du bloc : en tête de page, trois puces.
2. Sortir les pages transverses de leur section. L'avis, l'échelle de preuve et le glossaire peuvent aller dans un « Repères du dossier » en tête du site, ou au moins être décrits comme valables pour tout le dossier. Le glossaire doit alors définir le vocabulaire de décision, et l'accueil y renvoyer.
3. Ajouter à l'analyse LPI une page « Données de Projects » : modèle, export, identifiants, réversibilité.
4. Faire pointer les pages de contenu vers les pages qui font foi : scenarios-de-besoin.mdx:74 vers la carte des briques, puis laisser Les sous-projets en clair à son rôle de relecture ; décrire la restitution ailleurs que dans le livrable final de cette section, ou assumer ce rôle dans le titre de la section.
5. Ramener les 30 « En bref » à trois lignes et raccourcir les lignes de plus de 60 mots.
6. Fixer un nom par objet et l'appliquer partout :
   • le registre : « Questions à LPI et à CRISalid », sur l'accueil, dans D2 et dans les six renvois « grille d'évaluation » ;
   • les deux parties : « Partie 1 · Vitrine en marque blanche », « Partie 2 · Contribution des chercheurs » dans la navigation ;
   • les liens de l'accueil : le libellé de la page qu'ils ouvrent, et une ligne pour l'équipe CRISalid de la DiBISO ;
   • chaque brique : un nom courant, suivi une fois du nom du dépôt ;
   • « POC de pertinence » ;
   • « À confirmer » réservé au statut, et « non évalué » ajouté à l'échelle ou remplacé par un de ses statuts.
7. Marquer « Stratégie de rendu cible » en Projection Saclay (03-seo-rendu.mdx:37).
8. Déclarer la langue française du site et de l'index de recherche, et retirer l'ancien index de docs/public/pagefind/ s'il ne sert plus.
9. Réduire les annexes de veille à un tableau d'une ligne par plateforme, et fusionner les pages en double de l'audit de la documentation.
10. Harmoniser les libellés de navigation (casse, « et ») et retirer du script les clés de rang en double.
11. Renuméroter les dossiers dans l'ordre de lecture, avec redirections, si l'auteur accepte le changement d'URL.