Contribuer aux documents Web MDN

MDN Web Docs documente la plate-forme Web depuis plus de douze ans et est maintenant un effort multiplateforme avec des contributions et un conseil consultatif composé de membres de Google, Microsoft et Samsung ainsi que de représentants de Firefox. Ce qui est fondamental pour MDN, c'est qu'il s'agit d'un énorme effort communautaire, la communauté Web aidant à créer et à maintenir la documentation. Dans cet article, je vais vous donner quelques indications sur les endroits où vous pouvez aider à contribuer à MDN et exactement comment le faire.

Si vous n'avez jamais contribué à un projet open source auparavant, MDN est un excellent point de départ. Les compétences requises vont de la révision, de la traduction de l'anglais vers d'autres langues, des compétences HTML et CSS pour la création d'exemples interactifs, ou un intérêt pour la compatibilité des navigateurs pour la mise à jour des données de compatibilité des navigateurs. Ce que vous n'avez pas besoin de faire, c'est d'écrire beaucoup de code pour contribuer. C'est très simple et c'est un excellent moyen de redonner à la communauté si vous avez déjà trouvé ces documents utiles.

Contribuer aux pages de documentation

Le premier endroit où vous voudrez peut-être contribuer est la documentation MDN elle-même. MDN est un wiki, vous pouvez donc vous connecter et commencer à aider en corrigeant ou en ajoutant à toute documentation pour CSS, HTML, JavaScript ou toute autre partie de la plate-forme Web couverte par MDN.

Pour commencer l'édition, vous devez vous connecter à l'aide de GitHub. Comme d'habitude avec un wiki, tous les éditeurs d'une page sont répertoriés et cette section utilisera votre nom d'utilisateur GitHub. Si vous regardez l'une des pages sur les contributeurs MDN répertoriés au bas de la page, l'image ci-dessous montre les contributeurs actuels de la page sur CSS Grid Layout.

Que pouvez-vous modifier ?

Les choses que vous pourriez considérer en tant qu'éditeur corrigent les fautes de frappe et les erreurs grammaticales évidentes. Si vous êtes un bon relecteur et réviseur, vous pourrez peut-être améliorer la lisibilité des documents en corrigeant les fautes d'orthographe ou autres que vous remarquerez.

Vous pouvez également repérer une erreur technique, ou quelque part les spécifications ont changé et où une mise à jour ou une clarification serait utile. Avec la vaste gamme de fonctionnalités de plate-forme Web couvertes par MDN et le taux de changement, il est très facile que les choses deviennent obsolètes, si vous repérez quelque chose, corrigez-le !

Vous pourrez peut-être utiliser certaines connaissances spécifiques dont vous disposez pour ajouter des informations supplémentaires. Par exemple, Eric Bailey a ajouté des sections sur les problèmes d'accessibilité à de nombreuses pages. C'est un effort brillant pour mettre en évidence les choses auxquelles nous devrions penser lorsque nous utilisons une certaine chose.

Un autre endroit que vous pouvez ajouter à une page consiste à ajouter des liens "Voir aussi". Il peut s'agir de liens vers d'autres parties de MDN ou vers des ressources externes. Lors de l'ajout de ressources externes, celles-ci doivent être très pertinentes pour la propriété, l'élément ou la technique décrite par ce document. Un bon candidat serait un didacticiel qui montre comment utiliser cette fonctionnalité, quelque chose qui donnerait à un lecteur à la recherche d'informations une prochaine étape précieuse.

Comment modifier un document ?

Une fois connecté, vous verrez un lien vers Modifier sur les pages de MDN, en cliquant dessus, vous serez dirigé vers un éditeur WYSIWYG pour modifier le contenu. Vos premières modifications seront probablement de petites modifications, auquel cas vous devriez pouvoir suivre votre nez et modifier le texte. Si vous apportez des modifications importantes, il serait utile de consulter d'abord le guide de style. Il existe également un guide d'utilisation de l'éditeur WYSIWYG.

Après avoir effectué votre modification, vous pouvez prévisualiser puis publier. Avant de publier, c'est une bonne idée d'expliquer ce que vous avez ajouté et pourquoi en utilisant le champ Commentaire de révision.

Traductions linguistiques

Ceux d'entre nous dont l'anglais est la première langue sont incroyablement chanceux lorsqu'il s'agit d'informations sur le Web, car ils peuvent obtenir à peu près toutes les informations que nous pourrions souhaiter dans notre propre langue. Si vous êtes capable de traduire des pages en anglais dans d'autres langues, vous pouvez aider à traduire les documents Web MDN, rendant toutes ces informations accessibles à davantage de personnes.

Si vous cliquez sur l'icône de langue sur n'importe quelle page, vous pouvez voir dans quelles langues ces informations ont été traduites et vous pouvez ajouter vos propres traductions en suivant les informations de la page Traduction des pages MDN.

Exemples interactifs

Les exemples interactifs sur MDN sont les exemples que vous verrez en haut de nombreuses pages de MDN, comme celui-ci pour la propriété grid-area .

Ces exemples permettent aux visiteurs de MDN d'essayer différentes valeurs pour les propriétés CSS ou d'essayer une fonction JavaScript, directement sur MDN sans avoir besoin de se rendre dans un environnement de développement pour le faire. Le projet d'ajout de ces exemples est en cours depuis environ un an, vous pouvez en savoir plus sur le projet et les progrès à ce jour dans le post Apporter des exemples interactifs à MDN.

Le contenu de ces exemples interactifs est conservé dans le référentiel GitHub des exemples interactifs. Par exemple, si vous souhaitez localiser l'exemple de grid-area, vous le trouverez dans ce référentiel sous live-examples/css-examples/grid . Sous ce dossier, vous trouverez deux fichiers pour grid-area , un fichier HTML et un fichier CSS.

grid-area.html

 <section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>

grid.area.css

 .example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }

Un exemple interactif est juste une petite démo, qui utilise des classes et des identifiants standard afin que le framework puisse récupérer l'exemple et le rendre interactif, où les valeurs peuvent être modifiées par un visiteur de la page qui veut voir rapidement comment il œuvres. Pour ajouter ou modifier un exemple interactif, créez d'abord le référentiel d'exemples interactifs, clonez-le sur votre ordinateur et suivez les instructions de la page Contribuer pour installer les packages requis à partir de npm et pouvoir créer et tester des exemples localement.

Créez ensuite une branche et modifiez ou créez votre nouvel exemple. Une fois que vous en êtes satisfait, envoyez une demande d'extraction au référentiel d'exemples interactifs pour demander que votre exemple soit examiné. Afin de garder les exemples cohérents, les critiques sont assez pointilleuses mais doivent indiquer clairement les modifications que vous devez apporter, afin que vous puissiez mettre à jour votre exemple et le faire approuver, fusionner et ajouter à une page MDN.

Avec à peu près tout le CSS maintenant couvert (en plus des exemples JavaScript), MDN recherche maintenant de l'aide pour construire les exemples HTML. Il y a des instructions sur la façon de commencer dans un message sur le forum de discussion MDN. Consultez ce message car il donne des liens vers un document Google que vous pouvez utiliser pour indiquer que vous travaillez sur un exemple particulier, ainsi que d'autres informations utiles.

Les exemples interactifs sont incroyablement utiles pour les personnes qui explorent la plate-forme Web. Ajouter au projet est donc un excellent moyen de contribuer. Contribuer à des exemples CSS ou HTML nécessite une connaissance du CSS et du HTML, ainsi que la capacité d'imaginer une démonstration claire. Ce dernier point est souvent la partie la plus difficile, j'ai créé beaucoup d'exemples interactifs CSS et j'ai passé plus de temps à réfléchir au meilleur exemple pour chaque propriété qu'à écrire le code.

Données de compatibilité du navigateur

Assez récemment, les données de compatibilité des navigateurs répertoriées sur les pages MDN ont commencé à être mises à jour via le projet de compatibilité des navigateurs. Ce projet développe des données de compatibilité de navigateur au format JSON, qui peuvent afficher les tables de compatibilité sur MDN mais aussi être des données utiles à d'autres fins.

Les données de compatibilité du navigateur se trouvent sur GitHub, et si vous trouvez une page qui contient des informations incorrectes ou qui utilise toujours les anciennes tables, vous pouvez soumettre une demande d'extraction. Le référentiel contient des informations de contribution, cependant, la façon la plus simple de commencer est de modifier un exemple existant. J'ai récemment mis à jour les informations de la propriété CSS shape-outside . La propriété comportait déjà des données dans le nouveau format, mais elles étaient incomplètes et incorrectes.

Pour modifier ces données, j'ai d'abord forké les données de compatibilité du navigateur afin d'avoir mon propre fork. J'ai ensuite cloné cela sur ma machine et créé une nouvelle branche pour y apporter mes modifications.

Une fois que j'ai eu ma nouvelle branche, j'ai trouvé le fichier JSON pour shape-outside et j'ai pu faire mes modifications. J'avais déjà une bonne idée de la prise en charge du navigateur pour la propriété ; J'ai également utilisé l'exemple en direct sur la page MDN shape-outside pour tester le support lorsque je n'étais pas sûr. Par conséquent, effectuer les modifications consistait à travailler sur le fichier, à vérifier les numéros de version répertoriés pour la prise en charge de la propriété et à mettre à jour ceux qui étaient incorrects.

Comme le fichier est au format JSON, il est assez simple à modifier dans n'importe quel éditeur de texte. Le fichier .editorconfig explique les règles de formatage simples pour ces documents. Il y a aussi quelques conseils utiles dans cette liste de contrôle.

Une fois que vous avez effectué vos modifications, vous pouvez valider vos modifications, pousser votre branche vers votre fork, puis effectuer une demande d'extraction vers le référentiel de données de compatibilité du navigateur. Il est probable que, comme pour les exemples concrets, l'examinateur vous demandera d'apporter des modifications. Dans mon PR pour les données Shapes, j'ai eu quelques erreurs dans la façon dont j'avais marqué les données et j'ai dû apporter quelques modifications aux liens. Celles-ci étaient simples à réaliser, puis mes relations publiques ont été fusionnées.

Commencer

Vous pouvez commencer simplement en choisissant quelque chose à ajouter et en commençant à travailler dessus dans de nombreux cas. Si vous avez des questions ou avez besoin d'aide pour tout cela, le forum MDN Discourse est un bon endroit pour poster. MDN est l'endroit où je vais chercher des informations, l'endroit où j'envoie les nouveaux développeurs et les développeurs expérimentés, et sa force est le fait que nous pouvons tous travailler pour l'améliorer.

Si vous n'avez jamais fait de demande d'extraction sur un projet auparavant, c'est un endroit très convivial pour faire ce premier PR et, comme j'espère l'avoir montré, il existe des façons de contribuer qui ne nécessitent pas du tout d'écrire de code. Une compétence très précieuse pour tout projet de documentation est celle de la rédaction, de l'édition et de la traduction, car ces compétences peuvent aider à rendre la documentation technique plus facile à lire et accessible à un plus grand nombre de personnes dans le monde.