Documenter un projet reproductible
Écris des instructions qu'une autre personne peut vérifier.
Objectifs de la leçon
- Distinguer le rôle de chaque outil
- Produire une preuve observable
- Choisir une alternative accessible
1. Décrire le résultat, pas la marque
Commence par ce que le projet produit: une page locale, son fichier d'entrée et la façon de l'observer. Évite les phrases qui supposent un éditeur, un système ou un abonnement précis.
2. Écrire des étapes testables
Une bonne étape contient une action et un résultat attendu: « Ouvre <code>index.html</code>; le titre Atelier apparaît ». « Configure le projet » est trop vague pour diagnostiquer un échec.
3. Signaler les variantes
Donne une voie terminal et une voie graphique seulement lorsqu'elles apportent quelque chose. Mentionne l'aperçu intégré pour les environnements verrouillés. N'exige pas de droits administrateur si le projet n'en a pas besoin.
4. Conserver une preuve
Note le nom du fichier observé, le résultat attendu et un contrôle de dépannage. Ces éléments forment un contrat léger que l'on peut relire après une mise à jour ou sur une autre machine.
Vocabulaire lié
- Reproductible — Qui peut être refait avec le même résultat.
- Résultat attendu — Observation précise après une action.
- Prérequis — Condition nécessaire avant de commencer.
Validation
- J'ai produit l'artefact demandé
- J'ai observé le résultat
- Je peux expliquer une alternative