Comment documenter un en-tête HTTP

La référence des en-têtes HTTP sur MDN Web Docs documente les champs d'en-têtes HTTP. Ce sont des composants de la section d'en-tête des messages de requête et de réponse dans le protocole de transfert hypertexte (HTTP). Ils définissent les paramètres de fonctionnement d'une transaction HTTP. Cet article explique comment créer une nouvelle page de référence pour un en-tête HTTP.

Vous devrez avoir des connaissances en HTTP ou être prêt à vous familiariser avec ses détails.

Note : La documentation de nouvelles en-têtes HTTP doit d'abord avoir lieu en anglais avant de pouvoir traduire le nouveau contenu en français. L'organisation du contenu de MDN ne permet pas de créer du contenu en français si celui-ci n'existe pas déjà en anglais.

Étape 1 - Déterminer l'en-tête HTTP à documenter

Étape 2 - Vérifier les pages d'en-tête HTTP existantes

  • Les en-têtes HTTP existants sont documentés ici.
  • Il existe différentes catégories d'en-têtes : en-tête de requête, en-tête de réponse, et en-tête de représentation.
  • Trouvez la catégorie de l'en-tête que vous vous apprêtez à documenter (notez que certains en-têtes peuvent être à la fois des en-têtes de requête et des en-têtes de réponse, selon le contexte).
  • Accédez à une page de référence d'en-tête existant dans la même catégorie.

Étape 3 - Créer la page d'en-tête HTTP

Étape 4 - Rédiger le contenu

  • Vous pouvez soit partir de notre modèle de page d'en-tête HTTP, soit utiliser une structure copiée à partir de l'un des documents d'en-tête HTTP existants que vous avez trouvés à l'étape 2. C'est à vous de choisir.
  • Rédigez un texte sur le nouvel en-tête HTTP.
  • Assurez-vous d'avoir les sections suivantes :
    • Texte d'introduction dont la première phrase mentionne le nom de l'en-tête (en gras) et résume son objectif.
    • Un encart syntaxique contenant toutes les directives/paramètres/valeurs possibles de l'en-tête HTTP.
    • Une section expliquant ces directives/valeurs.
    • Une section d'exemples qui contient un cas d'utilisation pratique pour cet en-tête ou qui montre où et comment il se produit habituellement.
    • Une section de spécification listant les documents standards RFC pertinents.
    • Une section "Voir aussi" énumérant les ressources pertinentes.

Étape 5 - Ajouter des informations sur la compatibilité des navigateurs

  • Si vous avez consulté d'autres pages d'en-tête HTTP, vous verrez qu'il existe une macro {{Compat}} qui remplit une table du navigateur pour vous.
  • La page du tableau de compatibilité est générée à partir de données structurées. Si vous souhaitez contribuer à ces données, veuillez consulter les instructions à l'adresse https://github.com/mdn/browser-compat-data/blob/main/README.md et nous envoyer une pull request.

Étape 6 - Mise à jour de la liste des en-têtes HTTP

Assurez-vous que votre en-tête est répertorié dans une catégorie appropriée sur la page de référence des en-têtes HTTP.

Étape 7 - Révision du contenu

Après avoir créé la page d'en-tête, soumettez-la en tant que pull request. Un membre de notre équipe de révision sera automatiquement désigné pour réviser votre page.