Règles d'écriture

MDN Web Docs est un projet open source. Les sections ci-dessous décrivent nos règles pour ce que nous documentons et comment nous le faisons sur MDN Web Docs. Pour en savoir plus sur comment contribuer, consultez nos règles de contribution.

Ce que nous écrivons

Cette section explique ce que nous incluons ou non sur MDN Web Docs, ainsi que d'autres politiques, comme la documentation des nouvelles technologies, le processus de suggestion de contenu et l'acceptation des liens externes. C'est un bon point de départ si vous souhaitez écrire ou mettre à jour du contenu pour MDN.

Critères d'inclusion

Cet article détaille les critères pour qu'un contenu soit inclus sur MDN Web Docs, le processus de demande d'ajout de documentation, ainsi que les attentes et règles pour les personnes qui souhaitent proposer du contenu.

Guide de style rédactionnel

Le guide de style décrit la langue et le style utilisés pour rédiger sur MDN Web Docs. Il explique aussi comment présenter les exemples de code.

Règles pour la section « Apprendre le développement web »

La section « Apprendre le développement web » de MDN s'adresse spécifiquement aux personnes qui découvrent les bases du développement web, et nécessite donc une approche différente du reste du contenu. Cet article donne des conseils pour rédiger du contenu pédagogique.

Comment écrire pour MDN Web Docs

Cette section regroupe toutes les informations pour créer et modifier des pages, y compris les processus et techniques à respecter. Vous y trouverez comment débuter, une vue d'ensemble de la structure des pages, et où trouver des guides pratiques pour des tâches spécifiques. Cette section inclut notamment :

Comment rechercher une technologie

Cette section donne des conseils pratiques pour rechercher une technologie à documenter.

Comment créer, déplacer et supprimer des pages

Cette section explique comment créer, déplacer ou supprimer une page sur MDN Web Docs, ainsi que la gestion des redirections lors de ces opérations.

Comment utiliser le markdown

Le format markdown utilisé sur MDN Web Docs est basé sur le GitHub flavored markdown (GFM) ^(angl.). Cette section est un guide du markdown utilisé, y compris les formats pour les notes et listes de définitions.

Ajouter des images et médias

Cette section décrit les exigences pour inclure des médias dans les pages, comme les images.

Comment documenter une propriété CSS

Cet article explique comment rédiger une page de référence sur une propriété CSS, avec la structure et le contenu attendus.

Comment documenter une API

Cette section explique comment aborder la documentation d'une API Web.

Comment documenter un en-tête HTTP

Cet article explique comment créer une page de référence pour un en-tête HTTP.

Comment ajouter une entrée au glossaire

Cet article explique comment ajouter et lier des entrées dans le glossaire MDN Web Docs, ainsi que les règles de présentation du glossaire.

Types de pages sur MDN Web Docs

Chaque page sur MDN Web Docs a un type précis, qu'il s'agisse d'une référence CSS ou d'un guide JavaScript. Cette section liste les différents types de pages et propose des modèles pour chacun. Il est utile de les consulter pour choisir le bon type de page à rédiger.

Structures de page sur MDN Web Docs

Cette section présente les différentes structures de page utilisées pour garantir une présentation cohérente sur MDN Web Docs. Cela inclut :

Sections de syntaxe

La section de syntaxe d'une page de référence contient un encadré définissant la syntaxe exacte d'une fonctionnalité. Cet article explique comment rédiger ces encadrés.

Exemples de code

Il existe de nombreuses façons d'inclure des exemples de code dans les pages. Cette section les détaille et donne les règles de syntaxe pour chaque langage.

Bannières et avertissements

Parfois, un article nécessite un avertissement particulier, par exemple si la page traite d'une technologie obsolète ou déconseillée en production. Cet article présente les cas courants et la façon de les gérer.

Tableaux de spécifications

Chaque page de référence doit indiquer les spécifications dans lesquelles l'API ou la technologie a été définie. Cet article montre à quoi ressemblent ces tableaux et comment les ajouter.

Tableaux de compatibilité

MDN Web Docs utilise un format standard pour les tableaux de compatibilité. Cet article explique comment enrichir et maintenir la base de données utilisée pour générer ces tableaux, ainsi que leur intégration dans les articles.

Macros

Les macros sont des raccourcis utilisés dans les pages pour générer du contenu, comme des encadrés latéraux. Cette section liste les macros utilisées et leur utilité.

Mentions et informations sur la licence

Décrit notre politique d'utilisation du contenu MDN Web Docs ailleurs sur le web, comment obtenir l'autorisation de republier du contenu sur MDN, et des conseils pour faire des liens vers MDN.

Comment étiqueter une technologie

Cette section définit les termes obsolète, déconseillé et expérimental, et explique comment étiqueter une technologie, ainsi que les cas de suppression de contenu sur MDN Web Docs.