Rédiger un journal des modifications qui dit ce qui a changé et quoi faire

## Savoir qui lit le journal des modifications et quels changements le concernent Rédigez un journal des modifications pour les personnes concernées par les changements apportés au logiciel, et non comme une spécification validée par une machine ou un déversement brut de l’activité de développement. Chaque choix éditorial doit aider le lectorat à comprendre la version publiée avec moins d’effort. Avant de commencer la rédaction, déterminez : - La publication ou la version décrite. - Les personnes qui dépendent du produit, de la bibliothèque, du service ou de la documentation. - Les changements qui modifient le comportement, les attentes, la compatibilité, l’accessibilité, la sécurité ou les actions requises. - Les conventions établies de gestion des versions, de titres et d’entrées que le projet utilise déjà. Utilisez les conventions comme des outils, et non comme des substituts au discernement. Conservez une structure existante lorsqu’elle aide le lectorat à comparer les versions, mais ne forcez pas un changement à adopter une formulation trompeuse uniquement pour respecter une étiquette. Lorsqu’une règle doit être stricte, expliquez-en la raison afin que les personnes qui contribuent puissent l’appliquer judicieusement. Séparez les principes du journal des modifications des instructions de configuration et des procédures habituelles de contribution. Conservez un seul emplacement faisant autorité pour chaque type de recommandation et créez un lien vers celui-ci, au lieu de reproduire des instructions qui risquent de diverger. ## Ne garder que les changements qui touchent les lecteurs et dire pourquoi ils comptent Examinez les changements envisagés du point de vue du lectorat. Incluez un élément lorsqu’il modifie ce qu’une personne peut faire, observer, considérer comme fiable, configurer, migrer ou protéger. Excluez les activités internes qui n’ont aucun effet significatif, sauf si elles expliquent une conséquence pertinente pour l’exploitation ou la compatibilité. Pour chaque changement inclus, répondez aux questions suivantes : 1. Qu’est-ce qui a changé en termes observables ? 2. Qui est concerné et dans quelles conditions ? 3. Pourquoi ce changement est-il important ? 4. Le lectorat doit-il agir et, si oui, quelle action est requise ? Commencez par le résultat. Ajoutez uniquement le contexte nécessaire pour éviter les malentendus. Énoncez explicitement les conditions, les exceptions et les implications pour la migration ; ne les dissimulez pas derrière un résumé vague. Ne faites pas la promotion d’un outil particulier simplement parce qu’il est populaire et n’inventez pas un processus qui ne résout aucun problème de communication démontré. Préférez une entrée simple et le flux de travail existant du projet, sauf si l’approche actuelle empêche le lectorat de comprendre un changement important. Les consignes et les recommandations doivent inclure leur justification. Le lectorat doit pouvoir exprimer un désaccord éclairé, car le compromis et le bénéfice recherché sont visibles. ## Décrire chaque changement avec des mots simples, avec son effet et ce qu'il faut faire Utilisez un langage simple et présentez d’abord l’essentiel. Évitez les barrières excluantes, les raccourcis réservés aux initiés, la complexité ornementale et les phrases qui obligent le lectorat à reconstruire l’affirmation principale. Préférez une formulation qu’une personne non native peut comprendre dès la première lecture et qu’une personne chargée de la traduction peut traduire directement plutôt que réinterpréter. Maintenez ces éléments distincts : - Le changement lui-même : une description concrète du comportement précédent et du nouveau comportement. - L’incidence : les utilisateurs, les environnements, les versions ou les flux de travail concernés. - La raison : le problème résolu ou le principe protégé. - L’action : toute étape de mise à niveau, de configuration, de migration ou de vérification que le lectorat doit effectuer. N’exagérez pas le degré de certitude ni l’incidence. Si le comportement varie selon le contexte, précisez la condition au lieu d’émettre une instruction universelle. Si aucune action du lectorat n’est requise, n’en inventez pas. Utilisez une terminologie cohérente dans toutes les entrées et toutes les versions. Expliquez les termes spécialisés inévitables lors de leur première utilisation, préservez les distinctions importantes et évitez les euphémismes qui atténuent les avertissements ou les informations relatives aux changements incompatibles. Appliquez le même style clair et centré sur l’essentiel à la documentation associée, aux notes de contribution et aux messages de commit, afin que le journal des modifications soit étayé par des informations sources cohérentes. ## Vérifier que les traductions disent la même chose que l'original et laisser une personne trancher Considérez les traductions comme une composante à part entière de la communication des changements. Une traduction propre à une version doit soit exister, soit fournir des indications claires pour y contribuer. Elle doit rester exacte et cohérente avec la source canonique, tout en étant compréhensible dans sa propre langue et son propre contexte culturel. Maintenez la structure des pages, l’acheminement des versions et le balisage source suffisamment simples pour qu’une personne chargée de la traduction et non spécialiste de la programmation puisse les modifier. Avant de changer les titres, les identifiants, les relations entre versions ou les conventions de balisage, évaluez l’incidence du changement sur chaque langue et chaque version maintenues. Suivez cette séquence de révision : 1. Finalisez le sens de l’entrée canonique avant la traduction. 2. Consignez les versions et les langues qui nécessitent le changement. 3. Vérifiez que chaque traduction requise existe ou dispose d’une voie de contribution claire. 4. Comparez le sens traduit à la source canonique afin de repérer les omissions, les inversions, les conditions modifiées et les incohérences terminologiques. 5. Confiez la décision éditoriale finale à une personne qui connaît la langue et la culture. N’utilisez pas un texte généré par une machine pour remplacer une personne chargée de la traduction. Les vérifications automatisées ou assistées par un modèle peuvent repérer une couverture manquante et d’éventuelles incohérences, mais les personnes restent responsables du sens, de l’adéquation culturelle et de la formulation finale. ## Confier les vérifications répétitives à des outils simples et les décisions aux personnes Utilisez l’automatisation pour réduire les vérifications répétitives entre les langues, les versions et les environnements de présentation. Les vérifications de la couverture des traductions, les tests d’acheminement des versions, les outils d’aide à la comparaison sémantique, les contrôles d’accessibilité et les tests de régression visuelle ou fonctionnelle constituent de bons candidats. Préférez des outils courants et réutilisables qui, une fois créés, peuvent fonctionner localement ou hors ligne sans modèle. Un modèle de langage peut aider une fois à concevoir ou à mettre en œuvre un outil, mais la vérification obtenue doit pouvoir être inspectée et répétée, être peu coûteuse à exécuter et fonctionner de façon autonome. Les modèles ne doivent pas : - Remplacer les traducteurs humains ou la révision culturelle. - Décider des positions éditoriales du projet ou du sens de ses recommandations. - Justifier une fonctionnalité ou un processus qui ne répond à aucun besoin indépendant. Les personnes décident si une entrée du journal des modifications est exacte, utile et appropriée. Les outils fournissent des éléments probants ; ils ne sont pas responsables de la conclusion. Maintenez le système de publication simple et durable. Préférez la chaîne d’outils existante pour la compilation et la rédaction, et n’ajoutez une dépendance, un service, une base de données ou un nouvel environnement d’exécution que lorsqu’une exigence concrète ne peut pas être satisfaite en toute sécurité avec l’approche actuelle. Les outils de vérification réservés au développement ne doivent pas devenir des exigences de production inutiles. Avant de publier, confirmez que l’entrée canonique est claire, que les versions et les traductions requises sont couvertes, que les vérifications automatisées ont produit des résultats réels et qu’une personne a révisé le sens final.