Comment s'informer sur une technologie

Avant de commencer à documenter ou à mettre à jour quelque chose sur MDN Web Docs, il y a certaines choses que vous devriez préparer et planifier au préalable.

On suppose qu'avant de lire ce guide, vous avez une connaissance raisonnable de ce qui suit :

• Technologies web telles que HTML, CSS et JavaScript.
• Lecture des spécifications des technologies web. Vous les consulterez souvent lorsque vous documenterez les API.

Tout le reste peut être appris en cours de route.

Les ressources utiles pour rédiger toute documentation comprennent :

1. Les guides des bonnes pratiques pour MDN Web Docs : Vous êtes déjà ici, mais il est bon de parcourir tous les articles et de vous familiariser avec notre style d'écriture, les différents types de pages et les sections qu'elles incluent, ainsi que les différentes manières dont nous intégrons différentes parties de la page (comme les spécifications et la compatibilité des navigateurs).
2. La spécification la plus récente : Différents organismes de normalisation créent des spécifications pour les technologies documentées sur MDN Web Docs. Par exemple, TC39 pour JavaScript, WHATWG (en anglais) pour HTML et le W3C (en anglais) pour CSS, XML, et certaines API web. Les spécifications sont liées aux pages de référence sur MDN Web Docs (via la section « Spécifications »). Alternativement, vous pouvez généralement effectuer une recherche sur le Web. Travaillez toujours à partir de la spécification la plus récente et la plus à jour.
3. Les navigateurs web principaux les plus récents : Il s'agit généralement de versions expérimentales/alpha telles que Firefox Nightly, Chrome Canary ou Safari Technology Preview (en anglais), qui sont plus susceptibles de prendre en charge les fonctionnalités que vous documentez. Ceci est particulièrement pertinent si vous documentez une fonctionnalité en cours d'implémentation.
4. Démos/articles de blog/autres infos : Trouvez autant d'informations que possible. Si vous mettez à jour une technologie parce qu'elle a changé, assurez-vous que les ressources que vous utilisez pour apprendre ne sont pas obsolètes. C'est pourquoi les deux premiers points ci-dessus sont importants.

Cela peut sembler un peu étrange au début, mais plus vous le faites, plus vous vous y habituez. Voici quelques liens utiles pour vous aider à démarrer :

• Comment lire une spécification du W3C par J. David Eisenberg traduit depuis A List Apart
• Comprendre les spécifications CSS du W3C
• How to read web specs part I – or: WebVR, how do you work? (en anglais) explique comment lire la spécification WebVR en particulier, mais c'est une excellente introduction à la lecture des spécifications des API Web.
• How to read web specs part IIa – or: ECMAScript Symbols (en anglais) deuxième partie du lien ci-dessus, contient des informations sur la compréhension de la spécification ECMAScript qui définit le langage JavaScript

De plus, nous disposons du guide sur les informations contenues dans un fichier WebIDL, qui peut vraiment aider lors de la lecture des spécifications des API Web.

Vous reviendrez souvent à l'écriture d'exemples de code ou à la création de démonstrations au cours de la documentation d'une technologie, mais il est très utile de commencer par se familiariser avec le fonctionnement de celle-ci. C'est un exercice très utile, car il vous permet de bien comprendre les cas d'utilisation (pourquoi une développeuse ou un développeur utiliserait cette technologie) et vous aide à créer des exemples de code en même temps.

Les différentes pages que vous devez rédiger à partir de zéro ou mettre à jour varient en fonction de la technologie sur laquelle vous écrivez. Consultez les types de pages et la section correspondant à la technologie que vous documentez. Vous devrez probablement aussi mettre à jour la documentation existante, alors cherchez dans MDN Web Docs les pages qui sont liées à ce que vous écrivez.

Il est possible que les barres latérales des pages que vous écrivez doivent également être créées ou mises à jour. Pour savoir si cela est nécessaire et comment le faire, consultez le guide sur les barres latérales.

Certains des exemples de code pour MDN Web Docs sont conservés dans des dépôts séparés. Il s'agit notamment des exemples interactifs qui apparaissent dans la section « Essayer » des pages de référence et du code de démonstration plus volumineux nécessaire pour les guides. Si vous devez ajouter ou modifier l'un de ces dépôts, il est bon de le noter dans votre liste.

L'article sur les exemples de code décrit les différents types d'exemples de code que nous utilisons sur MDN Web Docs.

Si vous documentez une nouvelle API web, votre liste initiale de sections à documenter pourrait ressembler à ceci :

1. Page de vue d'ensemble
2. Pages d'interfaces
3. Pages de constructeurs
4. Pages de méthodes
5. Pages de propriétés
6. Pages d'évènements
7. Pages de concepts/guides
8. Exemples de code
9. Barres latérales

Vous pouvez ensuite l'enrichir avec plus de détails, en ajoutant chaque interface et ses membres. Par exemple, si vous documentiez l'API Web Audio, votre liste pourrait ressembler à ceci :

• API Web Audio
• AudioContext
  • AudioContext.currentTime
  • AudioContext.destination
  • AudioContext.listener
  • …
  • AudioContext.createBuffer()
  • AudioContext.createBufferSource()
  • …
• AudioNode
  • AudioNode.context
  • AudioNode.numberOfInputs
  • AudioNode.numberOfOutputs
  • …
  • AudioNode.connect(Param)
  • …
• AudioParam
• Évènements (mise à jour de la liste)
  • start
  • end
  • …

À ce stade, il est conseillé d'ouvrir un ticket sur le dépôt mdn/content avec les pages listées comme à faire (case à cocher). Cela vous permet, ainsi qu'aux autres personnes travaillant sur la documentation, de suivre publiquement l'état d'avancement. Vous pouvez également lier vos pull requests à ce ticket pour donner plus de contexte à tout le monde.

Si vous travaillez sur la traduction de pages, il vous faudra ouvrir vos tickets sur le dépôt mdn/translated-content. Un membre de notre équipe de révision sera automatiquement désigné pour réviser vos modifications.

Maintenant, créez les pages dont vous avez besoin. Pour créer une nouvelle page, consultez les instructions dans notre guide Créer et modifier des pages. Consultez également notre guide sur les types de pages pour des modèles de pages qui pourraient être utiles.