Corriger une documentation technique selon les règles du projet sans casser les liens

## Distinguer les fichiers modifiables des fichiers générés avant de modifier - Repérez où se trouvent les contenus rédigés, les inclusions réutilisables, les modèles, les données structurées, les ressources statiques et les références générées. - Considérez le guide de contribution, le guide de style, la référence des composants et les règles de métadonnées d’en-tête du dépôt comme des sources faisant autorité. - Avant toute modification, distinguez les sources modifiables des contenus intégrés depuis des sources externes ou générés. - Ne modifiez pas directement les fichiers intégrés depuis des sources externes ni les pages de référence générées. Remontez jusqu’à leur source en amont et effectuez la correction à cet endroit. - Lorsqu’un échec de validation locale provient d’un contenu protégé, signalez la source en amont responsable au lieu d’appliquer un contournement local. ## Utiliser les vrais chemins de fichiers dans les liens et vérifier chaque cible - Déterminez si le système de publication réécrit les chemins source, en retire des segments ou leur attribue des alias. - Utilisez le chemin source complet pour les références internes lorsque le système de compilation résout les liens par rapport à l’arborescence source, même si l’URL publique est plus courte. - Vérifiez les ancres par rapport aux identifiants de titre produits par le moteur de rendu réel, y compris les règles de mise en minuscules et de génération des slugs. - Vérifiez les liens de remplacement au lieu de les deviner. Si la destination ne peut pas être confirmée, considérez la modification comme bloquée, sauf si une migration établie autorise une URL plus sûre sans ancre. - Avant de modifier la référence d’une ressource manquante, inspectez le système de fichiers virtuel du framework et les ressources fournies par les dépendances, en plus du dossier source visible. ## Écrire court et direct avec les termes validés du projet - Rédigez de manière directe, concise et à la voix active. - Retirez les tournures hésitantes, le remplissage promotionnel, les commentaires métadiscursifs et les formulations présentant une tâche comme ne demandant aucun effort. - Privilégiez les instructions centrées sur le lecteur et nommez le produit ou le système lorsque la propriété doit être explicite. - Utilisez la terminologie, la casse, les verbes d’interface et les règles de mise en valeur approuvés par le dépôt. - Conservez les notes permanentes d’introduction de version lorsqu’elles expliquent quand un comportement a commencé ; évitez les termes relatifs dont le sens expire avec le temps. - Ajoutez les termes techniques légitimes à la liste de vocabulaire autorisé la plus restrictive. Utilisez la casse canonique et évitez les motifs trop larges qui neutralisent des vérifications sans rapport. ## Remplir le titre et la description de chaque page et bien écrire les composants - Incluez tous les champs de métadonnées obligatoires, tels que le titre de la page, la description d’aperçu et les mots-clés de recherche. - Maintenez les libellés de navigation dans les limites documentées et utilisez les champs de tri uniquement lorsque la section les exige. - Consultez la référence des composants avant d’écrire des shortcodes du framework ou des composants intégrés ; une syntaxe incorrecte peut échouer silencieusement tout en produisant un contenu défectueux. - Respectez le comportement documenté des directives d’interface côté client. Ne combinez pas deux mécanismes de masquage si l’un peut remplacer l’autre de façon permanente ; utilisez le mécanisme de masquage avant initialisation du framework. - Ne modifiez pas la configuration globale dans le seul but de contourner une limite de compilation locale ou d’arbre de travail. ## Mettre en forme et contrôler d'abord les fichiers changés, puis tout le site si besoin - Après la modification, exécutez l’outil de formatage fourni par le dépôt sur les fichiers modifiés. - Avant une validation plus large, exécutez l’analyseur limité aux fichiers qui combine les vérifications du balisage et du texte. - Pendant un travail incrémental, privilégiez les vérifications ciblées afin que des échecs sans rapport ne masquent pas le résultat. - Exécutez une compilation complète du site et des vérifications de liens lorsque la modification affecte le routage, les composants partagés, la navigation, les références générées ou d’autres comportements entre pages. - Dans les environnements où une cible de validation tout-en-un est incompatible, exécutez séparément les vérifications prises en charge et laissez la configuration inchangée. - Terminez les vérifications applicables sans attendre un rappel distinct et signalez toute vérification qui n’a pas pu être exécutée. ## Faire une petite modification par problème et répondre à chaque commentaire de relecture - Créez un seul ensemble de modifications ciblé pour chaque problème. Ne mélangez pas les nettoyages voisins ni les refactorisations sans rapport avec les corrections de documentation. - Placez explicitement les fichiers dans la zone de préparation. N’utilisez jamais de commandes de préparation générales susceptibles d’inclure des fichiers de verrouillage ou des modifications générées. - Avant de valider les modifications, inspectez la liste des fichiers préparés et retirez tout élément hors du périmètre documentaire prévu. - Confirmez que la destination de chaque envoi est la copie dérivée du contributeur ou un autre dépôt distant approuvé, et non le dépôt en amont protégé. - Traitez les rapports de problème et les suggestions de révision comme des affirmations à vérifier. Confirmez le comportement observé avant de modifier la documentation. - Répondez à chaque fil de révision après l’avoir traité, y compris aux commentaires portant sur une ligne précise qui peuvent nécessiter un appel distinct à l’API de révision. - Utilisez le point de terminaison du service dont la conservation des libellés et des métadonnées est avérée lorsqu’une commande pratique n’est pas fiable. ## Supprimer des pages ou ajouter une nouvelle version sans laisser de liens cassés - Avant de supprimer une page, recherchez son slug, son titre, ses alias et ses références entrantes dans le contenu rédigé et la configuration de navigation. - Lors du passage à une nouvelle référence versionnée, mettez à jour les paramètres de version centraux, créez la page de la nouvelle version et transférez sur celle-ci les alias de la version la plus récente depuis la page précédente, le tout dans une seule modification. - Ne laissez jamais deux pages de version revendiquer le même alias de version la plus récente. - Pour les références générées, modifiez la spécification ou le générateur en amont et régénérez le contenu ; ne modifiez pas manuellement la page générée. - Limitez les corrections au strict nécessaire, vérifiez l’échec réel et conservez une voie d’escalade claire lorsque la propriété ou les éléments externes ne sont pas établis.