1. MDN Web Docs
  2. Règles d'écriture
  3. Style rédactionnel

Cette page a été traduite à partir de l'anglais par la communauté. Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.

View in English Always switch to English

Guide de style rédactionnel

Ce guide de style rédactionnel décrit comment le contenu doit être rédigé, organisé, orthographié et mis en forme sur MDN Web Docs.

Ces directives visent à assurer la cohérence de la langue et du style sur l'ensemble du site. Cela dit, nous nous intéressons davantage au contenu qu'à sa mise en forme, vous n'avez donc pas à apprendre l'intégralité du guide de style avant de contribuer. Toutefois, ne soyez pas surpris·e si une autre personne modifie ensuite votre travail pour le conformer à ce guide. Les relecteur·ice·s pourront aussi vous renvoyer vers ce guide lors de la soumission d'une proposition de contenu.

Note : Les aspects linguistiques de ce guide s'appliquent principalement à la documentation en anglais. D'autres langues peuvent, et sont encouragées à, créer leur propre guide de style. Ceux-ci doivent être publiés comme sous-pages de la page de l'équipe de localisation correspondante. Cependant, ce guide reste à consulter pour la mise en forme et l'organisation du contenu.

Après avoir listé les lignes directrices générales, ce guide décrit le style de rédaction recommandé pour MDN Web Docs, puis la manière de mettre en forme différents composants d'une page, comme les listes et les titres.

Lignes directrices générales de rédaction

L'objectif est d'écrire des pages qui incluent toutes les informations dont les lecteur·ice·s peuvent avoir besoin pour comprendre le sujet traité.

Les sous-sections suivantes fournissent des recommandations pour y parvenir :

Considérez votre public cible

Gardez le public cible du contenu en tête. Par exemple, une page sur des techniques réseau avancées n'a vraisemblablement pas besoin d'entrer autant dans les détails sur les concepts de base du réseau qu'une page typique sur le réseau. Gardez à l'esprit qu'il s'agit de lignes directrices. Certains conseils peuvent ne pas s'appliquer dans tous les cas.

Considérez les trois C de la rédaction

Les trois C d'une bonne rédaction sont : clarté, concision et cohérence.

  • Clair : Assurez-vous que votre texte est clair et simple. En général, utilisez la voix active et des pronoms non ambigus. Écrivez des phrases courtes, une idée par phrase. Définissez les nouveaux termes, en tenant compte du public, avant de les utiliser.
  • Concis : Il est important de savoir quelle quantité d'information fournir. Trop de détails rend la page fastidieuse à lire et elle sera rarement utilisée.
  • Cohérent : Utilisez la même terminologie de manière cohérente sur la page et entre plusieurs pages.

Incluez des exemples pertinents

De manière générale, ajoutez des exemples ou des scénarios concrets pour mieux expliquer le contenu. Cela aide les lecteur·ice·s à comprendre les informations conceptuelles et procédurales de façon plus tangible et pratique.

Utilisez des exemples pour clarifier l'usage de chaque paramètre et préciser les cas limites éventuels. Vous pouvez aussi utiliser des exemples pour montrer des solutions à des tâches courantes et à des problèmes susceptibles de survenir.

Fournissez une introduction descriptive

Assurez-vous que le ou les premiers paragraphes avant le premier titre résument adéquatement les informations que la page va couvrir et ce que les lecteur·ice·s pourront accomplir après lecture. Ainsi, la personne qui lit peut déterminer rapidement si la page est pertinente pour ses besoins et ses objectifs d'apprentissage.

Dans un guide ou un tutoriel, l'introduction doit informer des sujets traités ainsi que des prérequis éventuels. Le premier paragraphe doit mentionner les technologies et/ou API documentées ou discutées, avec des liens vers les informations associées, et donner des indications sur les situations où le contenu de l'article sera utile.

  • Exemple d'introduction trop courte : Cet exemple d'introduction est beaucoup trop court. Il omet trop d'informations, comme ce que signifie exactement « tracer » du texte, où le texte est dessiné, et ainsi de suite.

    CanvasRenderingContext2D.strokeText() dessine une chaîne.

  • Exemple d'introduction trop longue : Cet exemple met à jour l'introduction, mais elle devient alors trop longue. Trop de détails sont inclus, et le texte part trop en profondeur dans la description d'autres méthodes et propriétés. L'introduction devrait plutôt se concentrer sur la méthode strokeText() et renvoyer vers les guides appropriés pour les autres détails.

    Lorsqu'elle est appelée, la méthode CanvasRenderingContext2D.strokeText() de l'API Canvas 2D trace les contours des caractères de la chaîne spécifiée à partir des coordonnées indiquées, en utilisant la couleur de stylo courante. En imagerie informatique, « tracer » un texte signifie dessiner le contour des glyphes de la chaîne sans remplir chaque caractère avec de la couleur.

    Le texte est dessiné en utilisant la police courante du contexte telle que définie par la propriété font du contexte.

    Le placement du texte par rapport aux coordonnées spécifiées est déterminé par les propriétés textAlign, textBaseline et direction du contexte. textAlign contrôle le placement de la chaîne par rapport à l'abscisse spécifiée ; si la valeur est "center", la chaîne est dessinée à partir de x - (stringWidth / 2), plaçant l'abscisse spécifiée au milieu de la chaîne. Si la valeur est "left", la chaîne est dessinée à partir de la valeur de x spécifiée. Et si textAlign vaut "right", le texte est dessiné de sorte qu'il se termine à l'abscisse spécifiée.

    (…)

    Vous pouvez, en option, fournir un quatrième paramètre qui permet d'indiquer une largeur maximale pour la chaîne, en pixels. Si vous fournissez ce paramètre, le texte est compressé horizontalement ou mis à l'échelle (ou autrement ajusté) pour tenir dans un espace de cette largeur lors du rendu.

    Vous pouvez appeler la méthode fillText() pour dessiner les caractères d'une chaîne remplis avec une couleur au lieu de ne tracer que leurs contours.

  • Exemple d'introduction appropriée : La section suivante donne un bien meilleur aperçu de la méthode strokeText().

    La méthode CanvasRenderingContext2D strokeText(), qui fait partie de l'API Canvas 2D, trace les contours des caractères d'une chaîne donnée, ancrés à la position indiquée par les coordonnées X et Y fournies. Le texte est dessiné en utilisant la police courante du contexte, et est justifié et aligné selon les propriétés textAlign, textBaseline et direction.

    Pour plus de détails et des exemples, voir la section Texte de la page « Dessiner des graphiques » ainsi que notre article principal sur le sujet, Dessiner du texte.

Utilisez un langage inclusif

MDN a un public large et divers. Nous recommandons fortement de rendre le texte aussi inclusif que possible. Voici des alternatives à certains termes couramment utilisés dans la documentation :

  • Évitez maître et esclave, préférez principal et réplica.
  • Remplacez liste blanche et liste noire par liste d'autorisation et liste d'interdiction.
  • Sanity doit être remplacé par cohérence.
  • À la place de dummy, utilisez exemple.
  • Vous ne devriez pas avoir besoin d'utiliser fou et insensé dans la documentation ; si c'est le cas, envisagez d'utiliser fantastique à la place.

Il est préférable d'utiliser un langage épicène lorsque le genre n'est pas pertinent. Par exemple, si vous parlez des actions d'un homme spécifique, utiliser « il »/« son » convient ; mais si le sujet est une personne de n'importe quel genre, « il·elle »/« son·sa » n'est pas approprié.

Exemples :

  • Incorrect : « Une boîte de dialogue de confirmation demande à l'utilisateur s'il souhaite autoriser la page à utiliser sa webcam. »
  • Incorrect : « Une boîte de dialogue de confirmation demande à l'utilisatrice si elle souhaite autoriser la page à utiliser sa webcam. »

Les deux versions sont genrées. Pour corriger, utilisez des pronoms neutres :

  • Correct : « Une boîte de dialogue de confirmation demande à l'utilisateur·ice s'il·elle souhaite autoriser la page à utiliser sa webcam. »

Note : MDN Web Docs autorise l'usage du pluriel de troisième personne comme « singular they » en anglais. Les pronoms neutres incluent « they », « them », « their » et « theirs ».

Une autre option consiste à mettre les utilisateur·ice·s au pluriel :

  • Correct : « Une boîte de dialogue de confirmation demande aux utilisateur·ice·s s'il·elle·s souhaitent autoriser la page à utiliser leurs webcams. »

La meilleure solution reste de réécrire pour éliminer les pronoms :

  • Correct : « Une boîte de dialogue de confirmation demandant l'autorisation d'accéder à la webcam apparaît. »
  • Correct : « Une boîte de dialogue qui demande l'autorisation d'utiliser la webcam apparaît. »

Cette dernière approche est sans doute préférable. Non seulement elle est plus correcte grammaticalement, mais elle supprime une partie de la complexité liée aux genres dans différentes langues qui peuvent avoir des règles très différentes. Cette solution peut faciliter la traduction, autant pour les lecteur·ice·s que pour les traducteur·ice·s.

Utilisez un langage accessible

Évitez les mots spatiaux et directionnels, comme « au-dessus », « au-dessous », « gauche », « droite » ou « ici ». Ces termes supposent une mise en page visuelle spécifique, qui peut ne pas s'appliquer à tout le monde. Ils peuvent aussi être ambigus ou trompeurs, en particulier pour les utilisateur·ice·s de lecteurs d'écran ou pour celles et ceux qui lisent du contenu traduit, où le langage directionnel peut être ambigu ou difficile à traduire correctement. Dans des mises en page réactives, où la position du contenu change selon la taille d'écran, ces références directionnelles peuvent devenir inexactes. Ce type de langage nuit à l'accessibilité et rend la navigation et la compréhension plus difficiles.

Utilisez à la place des formulations descriptives qui identifient clairement la section, le concept ou l'élément référencé. Référez-vous aux sections par leurs titres, et aux exemples ou extraits de code par ce qu'ils démontrent ou contiennent.

Par exemple :

  • Correct : « Reportez-vous à la section Accessibilité plus loin sur cette page. »

  • Incorrect : « Reportez-vous à la section d'accessibilité ci-dessous. »

  • Correct : « Dans l'exemple de code suivant, nous animons un cercle avec des transitions CSS. »

  • Incorrect : « Dans l'exemple de code ci-dessous, nous animons un cercle avec des transitions CSS. »

  • Correct : « Ce concept est expliqué dans la section précédente intitulée Créer une requête média. »

  • Incorrect : « Ce concept est expliqué dans la section ci-dessus. »

Évitez aussi les textes de lien vagues comme « Cliquez ici » ou « Lisez cet article ». Un texte de lien descriptif apporte un meilleur contexte pour toutes et tous et améliore l'expérience des technologies d'assistance.

En suivant ces lignes directrices, vous contribuez à rendre la documentation MDN accessible, claire et utilisable par toutes et tous, quel que soit le mode d'accès à la page.

Rédigez en pensant au référencement

L'objectif principal de tout texte sur MDN Web Docs doit toujours être d'expliquer et d'informer à propos des technologies du Web ouvert afin que les développeur·euse·s puissent apprendre vite ce qu'iels veulent faire ou trouver les détails nécessaires pour peaufiner leur code. Il est néanmoins important que le contenu soit trouvable. Pour cela, gardez à l'esprit l'optimisation pour les moteurs de recherche (SEO) lors de la rédaction.

Cette section couvre les pratiques standard, recommandations et exigences pour aider les moteurs de recherche à catégoriser et indexer facilement notre contenu afin que les lecteur·ice·s trouvent ce dont iels ont besoin.

La liste de contrôle suivante est utile lors de la rédaction et de la relecture afin de s'assurer que la page et ses voisines seront correctement indexées par les moteurs :

  • Veillez à ce que les pages ne soient pas trop similaires : Si le contenu de différentes pages se ressemble trop textuellement, les moteurs de recherche considéreront que les pages traitent du même sujet même si ce n'est pas le cas. Par exemple, si une interface a les propriétés width et height, il est facile que les textes se ressemblent étonnamment sur les deux pages, avec quelques mots échangés et le même exemple. Cela complique le travail des moteurs pour différencier les pages, qui finissent par se partager le classement, rendant chacune plus difficile à trouver.

    Il est donc important de s'assurer que chaque page a son propre contenu. Les suggestions suivantes peuvent aider :

    • Expliquez davantage de notions distinctives : Cherchez des cas d'usage où il pourrait y avoir plus de différences qu'on ne le pense. Par exemple, pour width et height, parlez des différences d'usage de l'espace horizontal et vertical, et proposez une discussion adaptée. Vous pouvez mentionner par exemple l'usage de width pour faire de la place à une barre latérale, tandis que height gère le défilement vertical ou les pieds de page. Inclure des informations d'accessibilité est aussi utile et important.
    • Utilisez des exemples différents : Les exemples sont souvent encore plus similaires que le corps du texte, car ils peuvent utiliser plusieurs des mêmes méthodes ou propriétés. Écrivez donc un nouvel exemple, ou fournissez-en plusieurs, dont au moins certains différents.
    • Ajoutez des descriptions pour les exemples : Incluez un aperçu de ce que fait l'exemple ainsi qu'une explication de son fonctionnement, avec un niveau de détail adapté au sujet et au public cible.

    La façon la plus simple d'éviter une trop grande similarité est d'écrire chaque article à partir de zéro si le temps le permet.

  • Veillez à ce que les pages ne soient pas trop courtes : Si une page contient trop peu de contenu (appelées « pages maigres » en SEO), les moteurs de recherche ne les catalogueront pas correctement, voire pas du tout. Ces pages sont difficiles à trouver. À titre indicatif, veillez à ce que les pages ne fassent pas moins de 300 mots environ. N'allongez pas artificiellement une page ; considérez ce seuil comme un objectif minimal quand c'est possible.

    Ces lignes directrices de base peuvent aider à créer des pages suffisamment riches sans les encombrer de texte inutile :

    • Évitez les ébauches : Si l'article est une ébauche ou manque de contenu, complétez-le. Nous essayons d'éviter les pages « brouillon » sur MDN Web Docs, même si elles existent, et de nombreuses pages manquent de sections entières.

    • Vérifiez la structure de la page : Vérifiez que la page est structurée correctement pour son type de page. Assurez-vous que toutes les sections sont présentes et correctement remplies.

    • Assurez l'exhaustivité : Vérifiez que rien ne manque. Assurez-vous que tous les paramètres sont listés et expliqués. Couvrez les exceptions éventuelles — c'est un endroit où manquent souvent des informations.

    • Développez tous les concepts : Il est facile de donner une explication rapide. Assurez-vous que toutes les nuances sont couvertes. Y a-t-il des cas particuliers ? Des restrictions connues dont le lectorat devrait être informé ?

    • Ajoutez des exemples : Il devrait y avoir des exemples couvrant tous les paramètres ou au moins ceux que les personnes débutantes à intermédiaires utiliseront, ainsi que ceux avancés qui demandent des explications supplémentaires. Chaque exemple doit être précédé d'un aperçu de ce qu'il fait, des connaissances nécessaires, etc. Après l'exemple (ou entre des parties), ajoutez du texte expliquant le fonctionnement du code. Ne négligez pas les détails ni la gestion des erreurs. Gardez à l'esprit que les utilisateur·ice·s copieront vos exemples et que votre code finira en production. Voir nos recommandations pour les exemples de code pour plus d'informations.

    • Expliquez les cas d'usage : S'il existe des cas d'usage fréquents pour la fonctionnalité décrite, parlez-en. Au lieu de supposer qu'une personne déduira qu'une méthode peut résoudre un problème courant, ajoutez une section avec un exemple et une explication.

    • Ajoutez des informations sur les images : Incluez un texte alt approprié sur toutes les images et schémas. Ce texte, ainsi que les légendes, comptent, car les robots d'indexation ne lisent pas les images, donc le texte alt leur décrit le contenu.

      Note : Il n'est pas recommandé d'ajouter trop de mots-clés ni des mots-clés non liés au sujet pour tenter d'améliorer le classement. Ce type de comportement est repéré et souvent pénalisé. De même, n'ajoutez pas de matière répétitive et inutile ou des blocs de mots-clés dans la page pour gonfler sa taille et son classement. Cela nuit à la lisibilité et à nos résultats de recherche.

  • Concentrez-vous sur le sujet : Il est préférable d'écrire autour du sujet de la page plutôt qu'autour d'un mot-clé précis. Il est probable qu'il existe de nombreux mots-clés pour un sujet donné ; beaucoup d'expert·e·s SEO compilent une liste de 5 à 100 mots-clés à inclure selon la longueur de l'article. Cela diversifie le vocabulaire et réduit les répétitions.

Style de rédaction

Outre des phrases grammaticalement correctes en français, nous recommandons de suivre ces lignes directrices pour garder la cohérence sur MDN Web Docs.

Abréviations et acronymes

Une abréviation est une version raccourcie d'un mot plus long, tandis qu'un acronyme est un nouveau mot créé à partir des premières lettres d'une expression. Cette section décrit les règles pour les abréviations et acronymes.

  • Développements : À la première mention d'un terme sur une page, développez les acronymes susceptibles d'être inconnus. En cas de doute, développez. Mieux encore, liez l'article ou l'entrée du glossaire qui décrit la technologie.

    • Correct : « XUL (XML User Interface Language) est le langage XML de Mozilla… »
    • Incorrect : « XUL est le langage XML de Mozilla… »

  • Capitalisation et points : Utilisez des majuscules complètes et supprimez les points dans toutes les abréviations et acronymes, y compris pour des organisations comme « US » et « UN ».

    • Correct : XUL
    • Incorrect : X.U.L. ; Xul

  • Abréviations latines : Vous pouvez utiliser des abréviations latines courantes (etc., c-à-d., ex :) dans des parenthèses et des notes. Utilisez des points dans ces abréviations, suivis d'une virgule ou de la ponctuation adéquate.

    • Correct : « Les navigateurs (ex : Firefox) peuvent être utilisés… »
    • Incorrect : « Les navigateurs ex Firefox peuvent être utilisés… »
    • Incorrect : « Les navigateurs, ex. Firefox, peuvent être utilisés… »
    • Incorrect : « Les navigateurs, (ex: Firefox) peuvent être utilisés… »

    Dans le texte normal (c'est-à-dire hors notes ou parenthèses), utilisez l'équivalent en toutes lettres en français.

    • Correct : « … navigateurs web, et cetera. »

    • Incorrect : « … navigateurs web, etc. »

    • Correct : « Les navigateurs web tels que Firefox peuvent être utilisés… »

    • Incorrect : « Les navigateurs web ex, Firefox peuvent être utilisés… »

    Le tableau suivant résume les significations et équivalents français des abréviations latines :

    Abrév. Latin Français
    cf. confer compare
    ex. exempli gratia par exemple
    et al. et alii et autres
    etc. et cetera et cetera, et ainsi de suite
    c-à-d. id est c'est-à-dire, en d'autres termes
    N.B. nota bene notez bien
    P.S. post scriptum post-scriptum

    Note : Demandez-vous toujours si l'usage d'une abréviation latine est réellement utile. Certaines sont si peu utilisées que beaucoup de lecteur·ice·s les confondent ou ignorent leur sens.

    Assurez-vous aussi de les utiliser correctement. Par exemple, ne confondez pas « c-a-d. » avec « ex. », ce qui est fréquent.

  • Pluriels d'abréviations et d'acronymes : Pour former le pluriel, ajoutez s. N'utilisez jamais d'apostrophe.

    • Correct : CD-ROMs
    • Incorrect : CD-ROM's

  • « Versus », « vs. » et « v. » : Si vous utilisez la contraction, « vs. » est préférée à « v. » et peut être utilisée dans les titres. Ailleurs dans le texte, utilisez la forme développée « versus ».

    • Correct : ceci vs. cela
    • Incorrect : ceci v. cela
    • Correct : cela versus cela

Capitalisation

Utilisez les règles standards de capitalisation française dans le corps du texte et écrivez « World Wide Web » avec des majuscules. Il est acceptable d'utiliser « web » (seul ou comme modificateur) et « internet » en minuscules.

Note : Cette règle diffère d'une version précédente du guide, vous pouvez donc trouver de nombreuses occurrences de « Web » et « Internet » sur MDN. N'hésitez pas à les corriger lors d'autres modifications, mais n'éditez pas un article uniquement pour cela.

Les noms des touches de clavier utilisent la casse phrase, pas les majuscules complètes. Par exemple, « Entrée » et non « ENTRÉE ». La seule exception : vous pouvez utiliser « ESC » pour abréger la touche « Échap ».

Certains mots doivent toujours être capitalisés, comme les marques qui incluent des capitales ou les mots dérivés d'un nom propre (sauf dans du code qui impose une casse). Exemples :

  • Boolean (nommé d'après le logicien George Boole (angl.))
  • JavaScript (marque d'Oracle Corporation, à écrire comme trademarké)
  • Python, TypeScript, Django et autres langages et frameworks

Certains outils et projets ont leur capitalisation de marque. Cela peut être tout en minuscules (« npm » ou « webpack »), tout en majuscules (« UNIX », « GNOME », « VIM ») ou en casse mixte (« TypeScript », « macOS », « jQuery »).

La capitalisation officielle du site ou de la documentation doit toujours être respectée, même en début de phrase. Si vous n'aimez pas commencer par une minuscule, reformulez. Par exemple : « Vous pouvez utiliser le gestionnaire de paquets npm pour… » plutôt que « npm permet de… ».

Contractions

Notre style rédactionnel a tendance à être informel, donc vous pouvez utiliser des contractions (par exemple, « n'est pas », « ne peut pas », « ne devrait pas ») si vous le souhaitez.

Nombres et numéraux

  • Virgules : Dans le texte courant, utilisez des virgules uniquement pour les nombres de cinq chiffres et plus.

    • Correct : 4000 ; 54 000
    • Incorrect : 4,000 ; 54000

  • Dates : Pour les dates (hors échantillons de code), utilisez le format « 1er Janvier 1900 ».

    • Correct : 24 février 1906
    • Incorrect : February 24th, 1906 ; 24 February, 1906 ; 24/02/1906

    Vous pouvez aussi utiliser le format JJ/MM/AAAA.

    • Correct : 24/02/1906
    • Incorrect : 02/24/1906 ; 1906/24/02 ; 06/02/24

  • Décennies : Utilisez le format « 1990 ». N'utilisez pas d'apostrophe.

    • Correct : 1920
    • Incorrect : 1920'

Pluriels

Utilisez les pluriels français, pas les formes influencées par le latin ou le grec.

  • Correct : scénarios, maximums
  • Incorrect : scenarii, maxima

Apostrophes et guillemets

N'utilisez pas de guillemets ou d'apostrophes « courbes ». Sur MDN Web Docs, utilisez uniquement des guillemets droits et des apostrophes droites. En effet, nous devons choisir une seule forme pour la cohérence. Si des caractères courbes se glissent dans des extraits de code, même en ligne, des personnes pourraient les copier en pensant qu'ils fonctionnent, ce qui n'est pas le cas.

  • Correct : N'utilisez pas les « apostrophes courbes ».
  • Incorrect : N’utilisez pas les “apostrophes courbes.”

Virgules

La liste suivante décrit des situations courantes où il faut connaître les règles d'usage de la virgule :

  • Après une proposition introductive : Une proposition subordonnée introductive se trouve généralement au début d'une phrase. Utilisez une virgule après cette proposition pour la séparer de la proposition principale suivante.

    • Exemple 1 :
      • Correct : « Dans cet exemple, vous apprendrez à utiliser une virgule. »
      • Incorrect : « Dans cet exemple vous apprendrez à utiliser une virgule. »
    • Exemple 2 :
      • Correct : « Si vous cherchez des recommandations, consultez notre guide de style. »
      • Incorrect : « Si vous cherchez des recommandations consultez notre guide de style. »
    • Exemple 3 :
      • Correct : « Sur les plateformes mobiles, vous obtenez généralement un clavier numérique pour saisir des données. »
      • Incorrect : « Sur les plateformes mobiles vous obtenez généralement un clavier numérique pour saisir des données. »

  • Avant les conjonctions : La virgule dite « d'Oxford » est la virgule qui précède la conjonction dans une série de trois éléments ou plus. Sur MDN Web Docs, nous utilisons la virgule d'Oxford. Les virgules séparent aussi chaque élément de la liste.

    • Correct : « Je voyagerai en train, en avion, et en voiture. »
    • Incorrect : « Je voyagerai en train, en avion et en voiture. »

    N'utilisez pas de virgule avant « et » et « ou » dans une liste de deux éléments.

    • Correct : « Mon chien est mignon et intelligent. »
    • Incorrect : « Mon chien est mignon, et intelligent. »

    Utilisez une virgule avant « mais » si elles relient deux propositions indépendantes. Si la phrase devient trop longue ou complexe, envisagez de la scinder.

    • Exemple 1 :
      • Correct : « Vous pouvez effectuer cette étape, mais vous devez faire attention au paramètre du fichier. »
      • Incorrect : « Vous pouvez effectuer cette étape, mais vous devez faire attention au paramètre du fichier. »
    • Exemple 2 :
      • Correct : « Mon père est strict mais affectueux. »
      • Incorrect : « Mon père est strict, mais affectueux. »

  • Propositions restrictives et non restrictives : Une proposition restrictive est essentielle au sens de la phrase et ne nécessite pas de virgules. Elle est généralement introduite par « qui » et ne doit pas être précédée d'une virgule.

    • Correct : « Nous avons conçu un cours qui inclut toutes les informations essentielles dont vous avez besoin pour atteindre votre objectif. »
    • Incorrect : « Nous avons conçu un cours, qui inclut toutes les informations essentielles dont vous avez besoin pour atteindre votre objectif. »

    Une proposition non restrictive apporte une information additionnelle et n'est pas essentielle. Elle est généralement introduite par « qui » et doit être précédée d'une virgule.

    • Correct : « Vous rédigez une politique, qui est une liste d'origines autorisées pour chaque fonctionnalité. »
    • Incorrect : « Vous rédigez une politique qui est une liste d'origines autorisées pour chaque fonctionnalité. »

  • Avant « comme » : Si « comme » fait partie d'une proposition non restrictive et que le reste de la phrase est une proposition indépendante, utilisez une virgule avant « comme ».

    • Correct : « L'objet Array possède des méthodes pour manipuler les tableaux de différentes façons, comme les joindre, les inverser et les trier. »
    • Incorrect : « L'objet Array possède des méthodes pour manipuler les tableaux de différentes façons comme les joindre, les inverser et les trier. »

    Exemple sans virgule : la proposition contenant « comme » est ici essentielle au sens.

    • Correct : « Les applications web deviennent plus puissantes en ajoutant des fonctionnalités comme la manipulation audio et vidéo et en permettant l'accès aux données brutes via WebSockets. »
    • Incorrect : « Les applications web deviennent plus puissantes en ajoutant des fonctionnalités, comme la manipulation audio et vidéo, et en permettant l'accès aux données brutes via WebSockets. »

Traits d'union

Les mots composés ne doivent être traités avec un trait d'union que lorsque la dernière lettre du préfixe est une voyelle et qu'elle est identique à la première lettre du radical.

  • Correct : re-elect, co-op, e-mail
  • Incorrect : reelect, coop, email

Orthographe

Utilisez l'orthographe du français moderne.

De manière générale, utilisez la première entrée du Dictionnaire de l'Académie française, sauf si cette entrée est une variante ou est principalement utilisée dans une autre forme du français. Par exemple, si vous recherchez « événement », vous trouverez la mention « événement » comme forme principale, et « évènement » comme variante admise mais moins courante. N'utilisez pas les variantes orthographiques non recommandées.

  • Correct : événement
  • Incorrect : évènement

Note : Ceci ne concerne que la documentation anglaise.

Nous avons installé cSpell (angl.) pour détecter les fautes d'orthographe. Il s'exécute chaque semaine et génère un rapport d'erreurs d'orthographe (angl.) dans le dépôt. Vous pouvez aussi l'exécuter en local avec la commande :

bash
yarn lint:typos

Dans le dépôt, nous maintenons plusieurs listes de mots, situées dans .vscode/dictionaries (angl.), qui contiennent des mots validés absents des dictionnaires par défaut. Vous pouvez ajouter des mots à ces listes s'ils sont valides mais signalés par l'outil. Lisez .vscode/cspell.json (angl.) pour comprendre le contenu de chaque dictionnaire et la configuration de la vérification orthographique.

Terminologie

Voici nos recommandations pour certains termes techniques :

  • Éléments HTML : Utilisez le terme « élément » pour parler des éléments HTML et XML, plutôt que « balise ». En outre, l'élément doit être entouré de chevrons « <> » et stylé avec des accents graves (backticks). Par exemple, utiliser <input> entre accents graves l'affichera comme <input> comme attendu.

    • Correct : l'élément <span>
    • Incorrect : la balise span

    Sur MDN, vous pouvez en option indiquer l'élément HTML avec la macro HTMLElement, qui stylise l'élément, ajoute les chevrons « <> » et crée un lien vers sa page de référence.

    • Avec accents graves : <span>
    • Avec la macro : <span>

  • Paramètres vs. arguments : Le terme préféré sur MDN Web Docs est paramètres. Évitez « arguments » pour la cohérence quand c'est possible.

  • Actions d'interface : Dans des séquences de tâches, décrivez les actions avec l'impératif. Identifiez l'élément d'interface par son libellé et son type.

    • Correct : « Cliquez sur le bouton Modifier. »
    • Incorrect : « Cliquez sur Modifier. »

Voix

La voix active est préférée, mais la voix passive est acceptable compte tenu du ton informel de notre contenu. Restez cohérent·e.

Composants de page

Cette section liste les lignes directrices à suivre pour différentes parties de chaque page, comme les titres, notes, liens et exemples.

Exemples de code

Une page MDN Web Docs peut contenir plusieurs exemples de code. Les recommandations suivantes s'appliquent à l'écriture d'exemples :

  • Chaque extrait devrait inclure :
    • Titre : Un court titre ### (<h3>) décrivant le scénario démontré par l'exemple. Par exemple, « Utilisation de l'impression offset » et « Revenir au style du calque précédent ».
    • Description : Une brève description avant le code qui précise ce sur quoi attirer l'attention. Par exemple, « Dans l'exemple suivant, deux couches de cascade sont définies en CSS, base et special. »
    • Explication du résultat : Une explication après le code qui décrit le résultat et le fonctionnement.
  • En général, l'exemple doit non seulement montrer la syntaxe et l'usage de la fonctionnalité, mais aussi mettre en avant l'objectif et les situations où une personne développeuse voudrait ou devrait l'utiliser.
  • Si vous travaillez avec un grand exemple, il peut être pertinent de le scinder en parties plus petites qui peuvent être décrites individuellement.
  • Lors de l'ajout d'exemples interactifs, notez que tous les blocs de code d'un même type (HTML, CSS, JavaScript) sont concaténés avant l'exécution. Vous pouvez donc scinder le code en plusieurs segments, chacun avec ses propres descriptions, titres, etc. Cela rend la documentation de code très puissante et flexible.

Pour le style et la mise en forme des exemples, voir nos Recommandations de style pour les exemples de code.

Références (liens)

Lorsque vous faites référence à une autre page MDN ou à une section d'une page par son titre, utilisez la casse phrase dans le texte du lien (faites correspondre le titre). Utilisez la casse phrase même si elle diffère de celle du titre de la page ou de la section liée. N'utilisez pas de guillemets autour du texte du lien. Pour référencer une page par son titre :

Suivez un style cohérent pour les liens vers des sections dans une page :

  • Correct : « Pour plus d'informations, voir la section Allocation en JavaScript du guide Gestion de la mémoire. »

Si la section liée est sur la même page, vous pouvez indiquer sa position avec des formulations descriptives.

  • Correct : « Ce concept est décrit plus en détail dans la section Accessibilité de ce document. »
  • Incorrect : « Ce concept est décrit plus en détail dans la section Accessibilité ci-dessous. »

Sur MDN, une autre façon de lier une page de référence est d'utiliser une macro. Ces macros sont décrites sur la page Macros couramment utilisées. Par exemple, pour lier une page de référence d'un élément HTML, utilisez la macro HTMLElement, et pour une propriété CSS, utilisez CSSxRef.

Nous suivons des recommandations similaires dans les sections Voir aussi en fin de page de référence, de glossaire et de guides.

Liens externes

Les liens externes sont autorisés dans des situations spécifiques. Utilisez les règles ci-dessous pour décider si un lien externe est pertinent. Les demandes qui ajoutent des liens externes seront refusées si elles ne respectent pas ces règles.

Si vous envisagez d'ajouter un lien externe au contenu Apprendre le développement web, lisez aussi Lignes directrices du contenu d'apprentissage > Liens et intégrations partenaires.

De manière générale, si vous envisagez d'ajouter un lien externe, assurez-vous de minimiser les risques suivants :

  • Liens rompus ou obsolètes
  • Apparence d'un soutien ou d'une recommandation, en particulier pour des produits ou services commerciaux
  • Tentative d'utiliser MDN Web Docs pour diffuser du spam
  • Liens raccourcis qui masquent la destination

Note : Avant d'ajouter un lien externe, envisagez de renvoyer à un contenu au sein de MDN Web Docs. Les liens internes sont plus faciles à maintenir et augmentent la valeur de l'ensemble de MDN pour les lecteur·ice·s.

  • Bons liens externes : Ils mènent à des ressources pertinentes, durables et largement fiables. Préférez des liens vers un contenu :

    • Unique ou indispensable (par exemple, une RFC de l'IETF)
    • Nécessaire pour l'attribution ou la citation (par exemple, dans le cadre d'une licence Creative Commons)
    • Plus susceptible d'être maintenu que s'il était recopié sur MDN Web Docs (par exemple, des notes de version d'un fournisseur)
    • Libre ou communautaire, comme MDN Web Docs

  • Mauvais liens externes : Ils manquent de pertinence, de maintenabilité, d'accessibilité, ou posent des obstacles aux lecteur·ice·s. Évitez les liens vers un contenu :

    • Générique ou non spécifique (par exemple, la page d'accueil d'un fournisseur plutôt que sa documentation pertinente)
    • Éphémère ou non maintenu (par exemple, une annonce ponctuelle)
    • Auto-liant ou auto-promotionnel (par exemple, le propre travail de l'auteur en dehors de MDN)
    • Payant derrière un péage (par exemple, un cours coûteux inaccessible à beaucoup)
    • Inaccessible (par exemple, une vidéo sans sous-titres)

  • Liens auto-promotionnels ou spam : Bien qu'un billet personnel, une conférence ou un dépôt GitHub puissent avoir de la valeur, les lier peut créer un conflit d'intérêts apparent. Réfléchissez à deux fois avant de lier des ressources avec lesquelles vous avez un lien personnel ou commercial.

    Note : Si vous avez une relation commerciale ou personnelle avec la cible d'un lien, vous devez la divulguer dans votre demande. Le non-respect peut mettre en péril votre participation à MDN Web Docs.

    Parfois, ces liens sont pertinents et appropriés. Par exemple, si vous êtes rédacteur·ice d'une spécification et contribuez à la documentation liée, alors lier cette spécification est attendu et acceptable. Mais vous devez divulguer la relation.

Un raccourcisseur d'URL peut être utile pour raccourcir des liens longs en adresses plus courtes et mémorisables. Cependant, ils masquent la destination. De plus, pour certains services, la destination peut être modifiée après création, ce qui peut être utilisé de manière malveillante.

N'utilisez pas de liens créés via des raccourcisseurs tiers ouverts. Par exemple, si https://monliencourt.lien/tototata est une URL courte générée par une personne et redirige vers https://exemple.fr/unlientroplong/details/show?page_id=tototata, utilisez l'URL longue d'exemple.fr.

À l'inverse, les raccourcisseurs de premier niveau gérés par l'organisation qui gère aussi la destination sont encouragés. https://bugzil.la est détenu et exploité par Mozilla et redirige vers https://bugzilla.mozilla.org/, également un domaine Mozilla. Dans ce cas, utilisez l'URL courte. Par exemple, utilisez https://bugzil.la/1682349 plutôt que https://bugzilla.mozilla.org/show_bug.cgi?id=1682349.

Niveaux de titres

Quand un nouveau paragraphe ouvre une nouvelle section, ajoutez un titre. Utilisez les niveaux de titre Markdown sans en sauter : ##, puis ###, puis ####, qui correspondent aux balises HTML de titres <h2>, <h3>, et <h4>.

## est le plus haut niveau autorisé, car # est réservé au titre de page. Nous recommandons de ne pas dépasser trois niveaux. Si vous pensez avoir besoin d'un quatrième niveau, envisagez de scinder l'article. Vous pouvez aussi présenter l'information sous forme de points pour éviter un niveau quatre.

Gardez à l'esprit les recommandations suivantes lors de la création de sous-titres :

  • N'ajoutez pas de sous-sections uniques. Ne subdivisez pas un sujet en un seul sous-sujet. C'est deux sous-titres ou plus, ou aucun.
  • N'utilisez pas de styles, classes ou macros en ligne dans les titres. Vous pouvez toutefois utiliser des accents graves pour indiquer des termes de code (par exemple, « Utiliser l'interface TotoTata »).
  • Évitez les « chocs de titres ». Ce sont des titres immédiatement suivis d'un sous-titre, sans texte entre les deux. Ce n'est pas esthétique et ne fournit pas de texte introductif au début de la section.

Images et autres médias

Si vous incluez des images ou d'autres médias sur une page, suivez ces règles :

Listes

Formatez et structurez les listes de manière cohérente sur toutes les pages. Chaque élément doit être rédigé avec une ponctuation appropriée, quel que soit le type de liste. Selon le type de liste, adaptez l'écriture comme décrit ci-dessous. Dans les deux cas, incluez une phrase d'introduction qui présente l'information de la liste.

  • Listes à puces : Utilisez-les pour regrouper des informations concises liées. Chaque élément doit suivre une structure similaire. Les phrases et les syntagmes (fragments sans verbe ou sujet) doivent respecter la ponctuation — les phrases finissent par un point, les syntagmes non.

    S'il y a plusieurs phrases dans un élément, un point doit clôturer chaque phrase, y compris la dernière, comme dans un paragraphe. Exemple :

    Dans cet exemple, nous devons inclure :

    • Une condition, avec une brève explication.
    • Une condition similaire, avec une brève explication.
    • Encore une condition, avec une explication supplémentaire.

    Remarquez la structure répétée d'un point à l'autre. Dans cet exemple, chaque point énonce une condition suivie d'une brève explication, et chaque élément se termine par un point.

    Si des éléments sont des phrases incomplètes, aucun point n'est requis à la fin. Par exemple :

    Les propriétés, liées à la couleur, utiles dans ce scénario sont :

    • propriétéA : Définit la couleur d'arrière-plan
    • propriétéB : Ajoute une ombre au texte

    Si un ou plusieurs éléments sont des phrases complètes, utilisez un point après chaque élément, même si l'élément contient trois mots ou moins. Dans la mesure du possible, uniformisez : soit toutes des phrases, soit tous des syntagmes.

  • Listes numérotées : Utilisées pour énumérer des étapes d'instructions. La clarté est prioritaire, surtout si chaque étape est longue. Comme pour les puces, respectez la ponctuation. Exemple :

    Pour structurer correctement une liste numérotée :

    1. Ouvrez par un titre ou un court paragraphe pour introduire les instructions. Il est important de donner le contexte.
    2. Rédigez vos instructions et gardez chaque étape dans son propre élément numéroté. Vos instructions peuvent être longues ; écrivez clairement et ponctuez correctement.
    3. Après les instructions, terminez par un court résumé ou une explication du résultat attendu.

    Exemple de conclusion pour la liste précédente :

    Nous avons créé une courte liste numérotée qui fournit des étapes pour produire une liste numérotée au bon format.

    Remarquez que les éléments des listes numérotées se lisent comme de courts paragraphes. Comme elles servent souvent à décrire une procédure, gardez chaque élément centré sur une étape : une étape par élément.

Section « Voir aussi »

La plupart des guides, pages de référence et même pages de glossaire sur MDN Web Docs contiennent une section Voir aussi à la fin de l'article. Cette section contient des références vers des sujets liés au sein de MDN et parfois des liens externes. Par exemple, voici la section Voir aussi de la page @layer.

En général, présentez les liens de la section Voir aussi sous forme de liste à puces avec chaque élément comme un syntagme. Dans la section Apprendre le développement web, la section Voir aussi suit un format de liste de définitions.

Pour maintenir la cohérence, gardez à l'esprit les points suivants lors de l'ajout ou la mise à jour d'une section Voir aussi.

Texte des liens

  • Le texte du lien doit être le même que le titre de la page ou de la section cible. Par exemple, le texte du lien vers la page ARIA intitulée « ARIA states and properties » sera :
  • Utilisez la casse phrase même si elle diffère du titre de la page ou de la section liée. Par exemple, le texte du lien vers la page Mode Quirks en casse phrase correcte sera :
  • Pour les liens externes, utilisez aussi la casse phrase même si la casse de l'article cible diffère. Exception : les titres de livres.

    Note : Si le lien mène vers une page en anglais, on ajoutera la mention « (angl.) » après le texte du lien.

  • Sur MDN, vous pouvez utiliser une macro pour lier une page, comme expliqué dans Lier des pages dans les références sur la page Macros couramment utilisées. L'usage d'une macro ajoute un formatage de code au mot-clé dans le texte du lien, comme ci-dessous.
  • Aucune ponctuation en fin d'élément, il s'agira d'un terme ou d'un syntagme.
  • Comme montré, ajoutez un formatage code avec des accents graves aux mots-clés et littéraux dans le texte du lien, même si ce formatage n'apparaît pas dans les titres. Par exemple, pour le titre « le constructeur Array() », le texte du lien sera le constructeur Array().

Texte descriptif

  • Gardez le texte descriptif autour du lien minimal. En cas de description, placez-la après le lien et un deux-points. Formulez comme un syntagme sans ponctuation finale. Gardez tout le texte lié en tête pour faciliter le balayage.
  • N'utilisez pas la conjonction « and » avant le dernier élément d'une série.
  • Pour les liens externes, essayez d'indiquer la source et l'année de publication ou de mise à jour entre parenthèses quand c'est pertinent. Cela renseigne la destination et aide la maintenance. Pour un article sur l'attente au niveau supérieur sur v8.dev (2019) :
  • Pour les livres, vous pouvez aussi fournir les auteur·ice·s. Évitez de le faire pour des billets de blog ou dépôts GitHub.

Ordre des liens

  • Listez d'abord les pages MDN de référence, puis les guides et tutoriels.
  • Si la liste mélange interne et externe, placez d'abord les liens internes.
  • À l'intérieur de chaque groupe, utilisez l'ordre alphabétique ou du simple vers l'avancé selon le contexte.

Sous-pages

Quand vous ajoutez des articles sur un sujet, vous le ferez typiquement en créant une page d'atterrissage, puis des sous-pages pour chaque article. La page d'atterrissage doit commencer par un ou deux paragraphes décrivant le sujet ou la technologie, puis fournir une liste des sous-pages avec leur description. Vous pouvez automatiser l'insertion des pages dans la liste à l'aide de macros.

Par exemple, le guide JavaScript est structuré comme suit :

Évitez de placer votre article au sommet de la hiérarchie, ce qui ralentit le site et nuit à la recherche et à la navigation.

Slugs

Le titre de page, affiché en haut, peut différer du « slug », qui est la partie de l'URL suivant <locale>/docs/. Gardez à l'esprit :

  • Les slugs doivent rester courts. Lors de la création d'un nouveau niveau de hiérarchie, son composant dans le slug doit tenir en un ou deux mots.
  • Utilisez des underscores pour les composants multi-mots, comme Basic_HTML_syntax dans /fr/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax.
  • Utilisez aussi la casse phrase pour chaque composant du slug, comme Basic_HTML_syntax ci-dessus.

Titres

Les titres sont utilisés dans les résultats de recherche et structurent la hiérarchie dans le fil d'Ariane. Un titre peut différer du « slug », comme expliqué dans la section Slugs.

Gardez à l'esprit :

  • Style de capitalisation : Utilisez la casse phrase pour les titres et sections sur MDN Web Docs (ne capitalisez que le premier mot et les noms propres) :

    • Correct : « A new method for creating JavaScript rollovers »
    • Incorrect : « A New Method for Creating JavaScript Rollovers »

    Beaucoup de pages plus anciennes ne respectent pas encore cette règle. Mettez-les à jour au besoin. Nous avançons progressivement.

  • Règles générales : Décider quoi documenter et comment structurer le contenu est l'une des premières étapes. Écrire une table des matières peut aider à ordonner l'information. Couvrez d'abord les concepts simples, puis les plus avancés. Traitez d'abord le conceptuel, ensuite l'actionnel.

    Recommandations pour les titres de page, sections et sous-sections :

    • Du plus large au plus précis : Comme indiqué dans Niveaux de titres, descendez de ## vers #### sans sauter. Utilisez les niveaux élevés pour les titres introductifs généraux et des titres plus spécifiques pour les niveaux inférieurs.
    • Regroupez logiquement : Assurez-vous que les sous-sections liées sont regroupées sous un titre de niveau supérieur. Nommer clairement les sections aide.
    • Titres courts : Des titres courts se balayent mieux dans le texte et la table des matières.
    • Titres spécifiques : Utilisez le titre pour indiquer l'information couverte. Par exemple, « Éléments HTML » plutôt que « Introduction ».
    • Titres focalisés : Un seul objectif par titre. Évitez autant que possible la conjonction « and ».
    • Construction parallèle : Utilisez un langage similaire pour des titres d'un même niveau. Par exemple, si un niveau ### utilise des gérondifs en « -ing », essayez de tous les écrire ainsi. Si un titre commence par un verbe à l'impératif (« Utiliser », « Configurer »), faites de même pour les autres au même niveau.
    • Évitez de répéter le titre parent : Ne répétez pas le texte d'un titre de niveau supérieur dans les titres de niveau inférieur. Par exemple, dans une section « Virgules », nommez une sous-section « Après une proposition introductive » plutôt que « Virgules après une proposition introductive ».
    • N'utilisez pas d'article initial : Évitez de commencer les titres par « a », « an » ou « the ».
    • Ajoutez un texte introductif : Après un titre, ajoutez un court texte pour expliquer ce qui sera couvert.

Voir aussi

Lectures complémentaires

Autres guides de style

Si vous avez des questions d'usage et de style non couvertes ici, nous recommandons le Guide de rédaction de Microsoft (angl.) ou le Manuel de style de Chicago (angl.).

Langue, grammaire et orthographe

Pour améliorer vos compétences en rédaction et en édition, les ressources suivantes peuvent aider :

Help improve MDN

Learn how to contribute

Cette page a été modifiée le par les contributeurs du MDN.

View this page on GitHub • Report a problem with this content