Chez Jérémie

Chez Jérémie, parfois c'est sérieux, parfois non !

Bien démarrer avec MDN

- Web - Lien permanent

Depuis maintenant 2 ans environ, je contribue activement à MDN (en particulier, j’écris la doc de la partie dédiée à SVG… en anglais pour l’instant) et depuis le début de l’année, j’organise tous les mercredis une petite soirée pour ceux qui veulent découvrir et aider à compléter la documentation du web ouvert chez Mozilla. A cette occasion, il y a un certain nombre de questions qui me sont posées régulièrement. En voici la liste avec les réponses qui vont bien.

Update : This article has been translate into English

Update 2 : Esteartículo fue traducido al castellano

C’est quoi MDN ?

Ne riez pas, vous n’imaginez pas le nombre de fois où j’ai entendu cette question.

Alors pour faire simple, MDN, c’est le “Mozilla Developer Network”. C’est un site web qui regroupe la quasi totalité de la documentation liée aux produits Mozilla. On y trouve 3 grandes sortes de ressources :

  • Des articles et des liens vers des ressources externes pour apprendre à utiliser les technologies du web
  • Des démos des dernières technologies implémentées dans les navigateurs modernes (Ces démo sont issues d’un concours mensuel, le “Dev Derby” organisé par John Karahalis)
  • Une documentation de références (API, balises, attributs, propriétés) des technologies Mozilla mais aussi et surtout de toutes les technologies du Web ouvert (HTML, CSS, Javascript, SVG, WebGL, etc.)

Cette dernière partie, la documentation des technologies Web, est la plus importante (autant en volume qu’en qualité) et celle sur laquelle, en ce moment, Mozilla porte ses plus gros efforts. Le point le plus notable de cette documentation c’est qu’elle est multi-navigateur avec des tables de compatibilité et des notes d’implémentation pour d’autres navigateurs que Firefox.

Même si cette documentation est sans doute une des plus riches documentations généralistes qui soit sur le Web, elle est loin d’être complète et c’est là que vous pouvez intervenir pour aider à la compléter ;)

Est-ce que c’est compliqué de participer ?

Pas du tout, au contraire, c’est affreusement simple. C’est même sans doute un des points d’entrée les plus faciles pour contribuer chez Mozilla (vous n’aurez pas besoin de vous confronter à Bugzilla :-P).

En effet, pour contribuer à MDN vous n’avez besoin que de 2 choses :

  1. Avoir envie
  2. Avoir un compte utilisateur sur MDN

Et c’est tout.

L’opération la plus difficile consiste à trouver le bouton “Connexion” dans la barre d’en-tête, coincé entre le champ de recherche et l’horrible onglet blanc “Mozilla”… oui, au niveau ergonomie on a fait mieux. Cliquez sur ce bouton puis fournissez une adresse e-mail et un mot de passe (le système de connexion utilise le nouveau système Persona/BrowserID). Sur la page suivante, on vous demandera un “Nom d’utilisateur” qui sera le nom affiché en face de vos contributions. Et voila, vous êtes prêt à contribuer.

De son coté, la contribution est elle aussi très simple. Fondamentalement, MDN est à 80% un wiki. Sur toutes les pages du Wiki, une fois que vous êtes identifié, vous trouverez un bouton “Editer” (en haut à droite). Cliquez dessus, le contenu de la page se chargera dans un éditeur WYSIWYG (rassurez vous, si vous préférez vous la jouer hardcore, vous pouvez repasser en édition HTML). Faites-y les modifications que vous voulez, enregistrez (via le bouton “Sauvegarder” en haut à gauche) et voilà. Vous avez fait votre première contribution à MDN et au projet Mozilla en général : pas de processus de validation à la mords-moi-le-nœud, pas de délai de publication, pas de modération à priori (mais il y en a tout de même une, assez light il est vrai, à posteriori)… trop facile :)

Qu’est-ce que je peux faire, par où je commence ?

La réponse courte, c’est “par ce que vous voulez”, malheureusement, l’expérience m’a montré que cette réponse n’était pas celle attendue par les nouveaux venus.

Basiquement, sur MDN, vous pouvez faire 2 choses :

  1. Proposer des démos via le “Dev Derby” mensuel, ce qui est une excellente façon de contribuer si vous êtes plutôt codeur.
  2. Enrichir la documentation si vous vous sentez plutôt une âme de rédacteur

La contribution à la documentation peut prendre plusieurs formes qui vont dépendre du temps que vous êtes prêt à y passer et/ou de votre degré de motivation :

  • Écrire de nouveaux articles
    C’est sans doute la contribution qui demande le plus de temps mais qui est aussi la plus utile au plus grand nombre. Notez que l’écriture de nouveaux contenus peut parfaitement se faire dans une autre langue que l’anglais ;)
  • Traduire des articles existants
    Ce n’est un secret pour personne, la partie anglaise de MDN est la plus fournie. Vous pouvez donc traduire ce que bon vous chante. Si vous avez envie mais ne savez pas quoi traduire, vous pouvez jeter un coup d’œil à la liste de l’ami Goofy.
  • Écrire des exemples de code
    La littérature, c’est bien, des exemples concrets, c’est mieux. En général, un bon exemple vaut mieux que dix paragraphes d’explications complètement absconses. Écrire des exemples de code fait partie des contributions les plus utiles (et pas forcément les plus longues à produire) et MDN en manque cruellement (en particulier sur la partie SVG… je dis ça, je dis rien, hein).
  • Faire de la relecture
    Comme MDN est faiblement modéré et comme l’erreur est humaine, il est toujours bon d’avoir des gens qui font de la relecture. Il peut s’agir aussi bien de relecture d’orthographe que de relecture technique. N’hésitez pas si vous avez peu de temps à consacrer car cela aidera beaucoup de monde (à titre d’exemple si vous lisez cet article, vous constaterez à quel point c’est désagréable de lire un texte bourré de fautes d’orthographe :-P).
  • Compléter les tables de compatibilité
    MDN se veut une documentation agnostique du point de vue des navigateurs. En conséquence, il existe des tables de compatibilité sur de nombreuse pages de MDN. Elles permettent de savoir pour quel navigateur, une API, une balise, un attribut ou une propriété est disponible. C’est particulièrement utile et cela prend 5 minutes pour rajouter une information de compatibilité. C’est sans doute la façon la plus facile et la plus rapide de contribuer à MDN.

Et surtout, un dernier conseil. La documentation est quelque chose d’immense, en conséquence vous n’aurez jamais le temps de tout faire tout seul. Concentrez-vous donc sur les sujets qui vous intéressent vous personnellement. Dans mon cas, c’est SVG, mais chacun aura son propre centre d’intérêt. S’il y a un sujet en particulier qui vous intéresse, sachez que MDN dispose de “Topic Leaders” qui peuvent vous aider (n’hésitez pas à les contacter, ils sont là pour ça)

Et si vous êtes francophone allergique à l’anglais, sachez que vous avez de la chance. En effet, trois de ces “responsables” sont francophones : Moi-même qui peut vous aider sur tous les sujets liés à SVG, David Bruant pour toutes les questions autour de Javascript et Jean-Yves Perrier pour CSS (Jean-Yves est aussi employé Mozilla sur MDN, n’hésitez donc vraiment pas à le contacter)… Vous noterez qu’ils ne s’occupent que de technologies au rabais :-P

Sachez également qu’il existe 2 pages sur MDN qui complètent très largement ce que je viens de résumer ici :

Je veux traduire une page en français, comment je fais ?

Cette question est plus compliquée qu’il n’y paraît. En effet, l’actuel moteur de Wiki qui fait tourner MDN n’est pas très bien fichu sur la question de la localisation. Heureusement, d’ici quelques semaines, la plateforme technique devrait changer (les travaux sont en cours, mais vous savez comme ça se passe chez Mozilla : « on livre quand c’est prêt. — C’est à dire ? — Quand c’est prêt. »).

D’ici là, voici les principaux points auxquels il faut prêter attention.

Localiser les URL

D’abord un petit point sur la structure des URL de MDN. Elles sont de la forme :

https://developer.mozilla.org/locale/page/sous-page/sous-sous-page

Pour toutes les pages liées à une technologie, localiser l’URL reviendra, dans 90% des cas, à changer la locale. Exemple :

Néanmoins, vous pouvez parfois vous retrouver face à ça :

Dans ce cas il y a grosso modo 2 options :

  1. Vous avez identifié une page manquante dans la partie française de MDN
  2. Vous avez identifié une page que vous aimeriez traduire dans une partie de MDN qui n’est pas en français.

Dans le premiers cas, vous êtes le plus souvent tombé sur un lien qui mène vers une page qui n’existe pas (ils sont stylés en rouge). Dans ce cas, le travail de localisation du lien a déjà été fait et il vous faut juste trouver la page équivalente en anglais (ou autre, selon ce que vous parlez comme langue). En général, en remontant les arborescences, vous trouverez facilement une page qui a été traduite et qui vous permettra d’explorer l’équivalent de ce que vous cherchez dans la langue de votre choix. Notez que pour passer d’une langue à l’autre, vous avez sur les pages, en haut à droite un menu “Langues” qui permet de passer d’une version à l’autre d’une même page. J’y reviens ci-après.

Dans le deuxième cas, c’est parfois un peu plus délicat car vous aller devoir faire des choix de traduction des termes de l’URL. Ici, la difficulté va être de s’assurer qu’une traduction des termes n’a pas déjà été faite sur une autre page. L’idée c’est d’arriver à être cohérents d’une traduction à l’autre… ce qui est particulièrement critique pour les URL. Ici, la meilleure façon de procéder, c’est d’aller poser la question aux localisateurs qui sont rompus à l’exercice. Pour le français, le meilleur point d’entrée c’est le canal IRC #frenchmoz sur irc.mozilla.org ou éventuellement la mailing liste de la communauté francophone des contributeurs Mozilla. Tous les détails sont disponibles sur mozfr.org

Faire des liens croisés entre les différentes localisations

La deuxième difficulté lorsqu’on localise une page, c’est de réaliser des liens croisés entre les différentes versions d’une même page. Ces liens croisés apparaissent dans le menu “Langues” en haut à droite des pages.

Le seul problème, c’est que ces liens ne sont pas générés automatiquement. Concrètement, vous devez rajouter dans chacune des pages localisées les liens vers les autres localisations. Oui, ça veut dire que s’il y a déjà 10 versions différentes d’une page, vous aller devoir toutes les éditer une par une pour rajouter manuellement le lien vers la nouvelle version que vous venez de créer.

Ce n’est pas bien compliqué (c’est un petit bout de code normalisé en bas de page), mais c’est assez fastidieux :-/

Bref, vivement le changement de plateforme technique.

Conclusion

Voilà, après ça, vous n’avez aucune excuse pour ne pas contribuer. Les problèmes de localisation mis à part (j’essayerai d’écrire un article sur le sujet quand on aura changé de plateforme) c’est facile et peu consommateur de temps. Si vous voulez en savoir plus, n’hésitez pas à passer dire bonjour le mercredi soir (je tiens une sorte de permanence dans les bureaux de Mozilla à Paris) ou à m’écrire (faites gaffe quand même, je réponds assez lentement). Au-delà de ça, d’autres peuvent vous aider si vous avez des questions sur la documentation : j’ai déjà cité les francophones David et Jean-Yves (aka Teoli)), mais chez les anglophones, vous pouvez facilement vous adresser à Eric Shepherd (aka Sheppy) et Janet Swisher. Vous pouvez facilement retrouver tout ce petit monde sur irc.mozilla.org sur la canal #devmo ou sur la liste de diffusion dev-mdc. Á noter que Jean-Yves, Eric et Janet sont les 3 principaux employés Mozilla chargés de superviser MDN, n’ayez donc aucun scrupule à vous adresser à eux (^_^)

La documentation c’est bon, mangez-en :)

MAJ du 25/04: Merci à Goofy pour la relecture orthographique :)