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.
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.