Un document pédagogique doit permettre de finir la tâche sans en ouvrir un autre. Recopier des commandes, des explications ou des extraits qui existent déjà ailleurs est un bon réflexe, pas une faute. Les renvois servent à approfondir, jamais à compléter une étape manquante.
Le cas qui a donné la règle
Un étudiant du cours de programmation et architecture passe à Kubuntu en pleine session et redemande
la procédure Java, Eclipse et JavaFX. Le matériel officiel du cours existe : quatre diaporamas sur le
Drive. Mais ils montrent des chemins Windows, C:\Librairie\java\openjfx en tête.
« Ne mets pas le diaporama officiel, le but est de le démêler, pas de le mêler. »
Puis, quand la règle a été mal généralisée en « une seule plateforme, une seule source », la correction : « Parfois on copie du matériel pour qu'il soit auto-portant. »
La nuance est la règle elle-même. Ce qui nuisait n'était pas la duplication, c'était d'envoyer le lecteur vers un document d'une autre plateforme au milieu d'une procédure. La réponse n'est donc pas « moins de contenu », c'est « un document complet pour son lecteur ».
Pourquoi
Trois raisons, dans l'ordre d'importance.
- La personne qui lit est déjà en difficulté. On consulte une procédure d'installation quand rien ne fonctionne. Chaque document supplémentaire à ouvrir est une occasion d'abandonner.
- Copier coûte quelques minutes, chercher coûte une soirée. L'asymétrie est énorme et elle penche toujours du même côté.
- Un document complet se corrige. Une procédure éparpillée sur trois supports ne se corrige jamais vraiment : on rafistole celui qu'on a sous la main.
Comment l'appliquer
Le test de l'auto-portance
Avant de publier, se poser une seule question : une personne qui n'a que ce document, sur sa machine à elle, peut-elle terminer la tâche ? Si la réponse exige d'ouvrir autre chose, le document n'est pas fini.
Distinguer les deux sortes de renvois
| Renvoi d'approfondissement | Renvoi de complétion |
|---|---|
| « Pour comprendre pourquoi le noyau 6.14 est la cible, voir la fiche du noyau. » | « Les commandes d'installation sont à la diapositive 14 du diaporama. » |
| Légitime : le lecteur peut finir sans cliquer. | À remplacer : recopier les commandes dans la fiche. |
Recopier avec les valeurs du lecteur
Copier n'est pas transcrire. Le contenu recopié s'adapte à la plateforme et au contexte de celui
qui lit : les chemins Windows deviennent des chemins Linux, /usr/lib/jvm/openjdk-17/
devient le vrai /usr/lib/jvm/java-17-openjdk-amd64 des paquets Ubuntu, et l'écart est
signalé si le lecteur risque de croiser l'autre version.
- Lire le document du début à la fin en ignorant tous les liens : la tâche se termine-t-elle ?
- Chercher les mots « voir », « comme dans », « à la diapositive » : chacun est un candidat au recopiage.
- Vérifier que chaque valeur exacte (chemin, nom de librairie, version) est écrite noir sur blanc, pas décrite.
Deux auto-portances : le guide et l'énoncé
Un énoncé et un guide ne sont pas auto-portants de la même façon. La règle vaut pour les deux, mais la tâche qu'ils portent n'est pas la même.
| Le guide : auto-portant pour l'exécution | L'énoncé : auto-portant comme contrat |
|---|---|
| Toutes les commandes, dans l'ordre, avec leurs vérifications et leurs pièges, recopiées même si elles existent ailleurs. | La mission, les étapes et leurs résultats attendus, les mesures, les livrables et le barème : complets. Le comment n'y est pas. |
| Sa tâche : faire. | Sa tâche : savoir exactement ce qui est demandé, et par quelle porte on l'exécute. |
Chaque étape de l'énoncé ouvre une porte vers l'étape du guide qui l'exécute. Recopier les commandes du guide dans l'énoncé n'est pas de l'auto-portance, c'est de la redondance : deux copies d'une même procédure finissent par diverger. Seule exception : la commande qui fait partie du vocabulaire d'examen, celle qu'on doit connaître par coeur.
Un laboratoire de cache dont l'énoncé recopiait les commandes de ses deux guides, et un collègue qui a vu la redondance avant nous. La règle avait été lue comme « recopier partout » ; elle dit « un document complet pour sa tâche ».
Les pièges
Deux copies d'une même commande finissent par diverger. Remède : dater la fiche, nommer la version des outils qu'elle vise (« Kubuntu 24.04, openjfx 17.0.16 »), et garder un script idempotent qui régénère la fiche plutôt que de la retoucher à la main.
Auto-portant ne veut pas dire « contient tout le cours ». La portée est une tâche : installer l'environnement, rendre un laboratoire, brancher un service web. Un document qui veut tout porter ne porte plus rien.
Mettre un lien est plus rapide que d'écrire la marche à suivre. C'est justement pour cela que c'est tentant, et que le lecteur paie la facture.
Ce que ça donne
Deux applications concrètes du 9 au 11 septembre 2026 :
- La fiche Installer Java, Eclipse et JavaFX sous Linux répète toutes les commandes au lieu de renvoyer à la page Environnement, et ne garde des liens que vers le zip du SDK et les téléchargements officiels.
- Le petit diaporama « Liens en cours » (deux diapositives, quatre adresses et un extrait de code) a été recopié dans l'outil cherchable des services web plutôt que laissé comme carte isolée dans la grille des semaines. Le deck reste en ligne, l'outil est devenu complet.
Et les pages de ce livre blanc : chacune embarque son CSS et son JavaScript. Un fichier, un lecteur, aucune dépendance.