Contribuer à MDN Web Docs
MDN Web Docs documente la plate-forme Web depuis plus de douze ans et est maintenant un effort multiplateforme avec des contributions et un comité consultatif avec des membres de Google, Microsoft et Samsung ainsi que ceux qui représentent Firefox. Ce qui est fondamental pour MDN, c'est que c'est un énorme effort communautaire, avec 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 contribuer à MDN et comment le faire.
Si vous n'avez jamais contribué à un projet open source auparavant, MDN est un endroit génial pour commencer. Les compétences requises vont de la révision, de la traduction de l'anglais à d'autres langues, des compétences HTML et CSS pour créer des exemples interactifs, ou un intérêt pour la compatibilité du navigateur pour la mise à jour des données de compatibilité du navigateur. Ce que vous n'avez pas besoin de faire 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.
Le premier endroit où vous pourriez vouloir contribuer est les documents MDN eux-mêmes. MDN est un wiki vous pouvez donc vous connecter et commencer à aider en corrigeant ou en ajoutant de la documentation pour CSS, HTML, JavaScript ou toute autre partie de la plateforme web couverte par MDN. 19659002] Pour commencer à éditer, vous devez vous connecter en utilisant GitHub. Comme d'habitude avec un wiki, tous les éditeurs d'une page sont listés, et cette section utilisera votre nom d'utilisateur GitHub. Si vous regardez l'une des pages sur les contributeurs MDN sont répertoriés en bas de la page, l'image ci-dessous montre les contributeurs actuels à la page sur CSS Grid Layout .
Choses que vous pourriez considérer comme un éditeur corrige des fautes de frappe et des erreurs grammaticales évidentes. Si vous êtes un bon correcteur et un bon réviseur, vous pourrez peut-être améliorer la lisibilité des documents en corrigeant toute faute d'orthographe ou toute autre erreur que vous déceleriez.
Vous pouvez également détecter 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 la plateforme Web couvertes par MDN et le taux de changement, il est très facile pour les choses d'être obsolètes, si vous repérez quelque chose – réparez-le!
Vous pourrez peut-être utiliser certaines connaissances spécifiques avoir à ajouter des informations supplémentaires. Par exemple, Eric Bailey a ajouté des sections sur les questions d'accessibilité à plusieurs pages. C'est un effort brillant pour mettre en évidence les choses auxquelles nous devrions penser quand nous utilisons une certaine chose.
Un autre endroit que vous pourriez ajouter à une page consiste à ajouter des liens "Voir aussi". Ceux-ci pourraient être des 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 tutoriel qui montre comment utiliser cette fonctionnalité, ce qui donnerait à un lecteur cherchant des informations une prochaine étape précieuse.
Comment éditer un document?
Une fois que vous êtes connecté, vous verrez un lien vers Modifier sur les pages dans MDN, en cliquant sur ceci vous emmènera dans un éditeur WYSIWYG pour éditer le contenu. Vos premières modifications sont susceptibles d'être de petits changements, auquel cas vous devriez pouvoir suivre votre nez et éditer le texte. Si vous faites des modifications importantes, alors il serait utile de jeter un coup d'œil au guide de style en premier. Il y a aussi un guide pour utilisant l'éditeur WYSIWYG .
Après avoir fait votre édition, vous pouvez Aperçu, puis Publier. Avant de publier, il est judicieux d'expliquer ce que vous avez ajouté et pourquoi utiliser le champ Commentaire de révision
Language Translations
Ceux d'entre nous qui ont l'anglais comme première langue sont incroyablement chanceux en ce qui concerne l'information sur le Web, étant en mesure d'obtenir à peu près toutes les informations que nous pourrions avoir dans notre propre langue. Si vous êtes en mesure de traduire des pages en anglais dans d'autres langues, vous pouvez aider à traduire MDN Web Docs, rendant ainsi toutes ces informations accessibles à davantage de personnes.
Si vous cliquez sur l'icône de la langue sur une page, vous pouvez voir dans quelles langues cette information a été traduite et vous pouvez ajouter vos propres traductions en suivant les informations sur la page Traduction des pages MDN . 19659021] 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
. d'un exemple interactif « />
Ces exemples permettent aux visiteurs de MDN d'essayer diverses valeurs pour les propriétés CSS ou d'essayer une fonction JavaScript, directement sur MDN sans avoir besoin de se diriger dans un environnement de développement pour le faire. Le projet pour ajouter ces exemples a été en cours pendant environ un an, vous pouvez lire sur le projet et le 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 Interactive Examples GitHub. Par exemple, si vous vouliez localiser l'exemple pour grid-area, vous le trouveriez dans ce repo 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: a;
grid-area: b;
grid-area: c;
grid-area: 2/1/2/4; ] Copier dans le Presse-papiers
.example-container {
couleur de fond: #eee;
frontière: .75em solide;
rembourrage: .75em;
affichage: grille;
grid-template-columns: 1fr 1fr 1fr;
grid-template-rows: répète (3, minmax (40px, auto));
zones de gabarit de grille:
"a a a"
"b c c"
"b c c";
intervalle de grille: 10px;
largeur: 200px;
}
.example-container> div {
couleur de fond: rgba (0, 0, 255, 0.2);
bordure: 3px bleu uni;
}
exemple-element {
background-color: rgba (255, 0, 200, 0,2);
bordure: 3px solide rebeccapurple;
}
Un exemple interactif est juste une petite démo, qui utilise des classes et des ID standards afin que le framework prenne l'exemple et le rende interactif, où les valeurs peuvent être changées par un visiteur de la page qui veut rapidement regarde comment ça marche. Pour ajouter ou éditer un exemple interactif, commencez par forker le repo Interactive Examples, clonez-le sur votre machine et suivez les instructions sur la page Contributing pour installer les paquets requis de npm et pouvoir construire et tester des exemples localement.
Puis créez une branche et éditez ou créez votre nouvel exemple. Une fois que vous êtes satisfait, envoyez une demande de tirage au dépôt des exemples interactifs pour demander que votre exemple soit examiné. Afin de garder les exemples cohérents, les critiques sont assez pointilleux mais devraient indiquer les changements que vous devez faire de façon claire, afin que vous puissiez mettre à jour votre exemple et le faire approuver, fusionner et ajouter à une page MDN.
Avec la quasi-totalité des CSS maintenant couverts (en plus des exemples JavaScript), MDN cherche maintenant de l'aide pour construire les exemples HTML. Il y a des instructions sur la façon de commencer à un article sur le Forum du discours de MDN . Consultez ce post car il contient 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 extrêmement utiles aux personnes qui explorent la plate-forme Web , donc ajouter au projet est un excellent moyen de contribuer. Contribuer à des exemples CSS ou HTML nécessite la connaissance de CSS et HTML, ainsi que la capacité d'imaginer une démonstration claire. Ce dernier point est souvent le plus difficile, j'ai créé beaucoup d'exemples CSS Interactive et j'ai passé plus de temps à trouver le meilleur exemple pour chaque propriété que j'en écris réellement.
Browser Compat Data
Récemment les données de compatibilité du navigateur répertoriées sur MDN Pages ont commencé à être mises à jour via le Browser Compatibility Project . Ce projet développe des données compat de navigateur au format JSON, qui peuvent afficher les tables de compatibilité sur MDN mais aussi être utiles à d'autres fins
Les données de compatibilité du navigateur sont sur GitHub et si vous trouvez une page contenant des informations incorrectes ou si vous utilisez toujours les anciennes tables, vous pouvez soumettre une demande Pull. Le référentiel contient des informations de contribution cependant, la façon la plus simple de commencer est d'éditer un exemple existant. J'ai récemment mis à jour les informations pour la propriété CSS shape-outside
. La propriété contenait déjà des données dans le nouveau format, mais celles-ci étaient incomplètes et incorrectes.
Pour modifier ces données, j'ai d'abord forké les données du navigateur de manière à avoir ma propre fourchette. J'ai ensuite cloné cela sur ma machine et créé une nouvelle branche pour faire mes changements.
Une fois ma nouvelle branche trouvée, j'ai trouvé le fichier JSON pour shape-outside
et j'ai pu faire mes modifications . J'avais déjà une bonne idée du support du navigateur pour la propriété; J'ai également utilisé l'exemple en direct sur la page MDN shape-outside pour tester le support quand je n'étais pas sûr. Par conséquent, effectuer les modifications nécessitait de travailler sur le fichier, en vérifiant les numéros de version répertoriés pour la prise en charge de la propriété et en mettant à jour ceux qui étaient incorrects.
Comme le fichier est au format JSON, il est assez simple à éditer dans n'importe quel éditeur de texte. Le fichier .editorconfig explique les règles de formatage simples de ces documents. Vous trouverez également quelques conseils utiles dans cette liste de contrôle
Une fois vos modifications effectuées, vous pouvez valider vos modifications, pousser votre branche vers votre fourche, puis effectuer une demande Pull dans le référentiel de données Compat du navigateur. . Il est probable que, comme pour les exemples en direct, le réviseur aura quelques modifications à apporter. Dans mon PR pour les données de formes j'ai eu quelques erreurs dans la façon dont j'avais marqué les données et nécessaire pour apporter des modifications aux liens. Ceux-ci étaient simples à faire, et puis mon RP a été fusionné.
Commencez
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, alors 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 de nouveaux développeurs et des 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 de tirage un projet avant, c'est un endroit très convivial pour faire ce premier PR et, comme j'espère l'avoir montré, il y a des façons de contribuer qui n'exigent pas d'écrire du code du tout. Une compétence très précieuse pour tout projet de documentation est d'écrire, d'éditer et de traduire, car ces compétences peuvent aider à rendre la documentation technique plus lisible et accessible à plus de gens à travers le monde
Source link