Comment rédiger un article pour aider les gens à se familiariser avec le Web

L'Espace d'apprentissage de MDN est le portail pour les articles qui présentent les concepts Web aux nouveaux développeurs. Parce que son contenu s'adresse surtout aux débutants, c'est un endroit idéal pour partager les connaissances et aider les nouveaux arrivants à connaître le Web. Il est important de s'assurer que les nouveaux développeurs peuvent comprendre ce contenu, c'est pourquoi nous y accordons une attention particulière.

Cet article explique comment écrire des pages pour l'Espace d'apprentissage.

Comment écrire un article pour l'Espace d'Apprentissage

 

Pour commencer à partager vos connaissances, cliquez simplement sur le gros bouton vert, puis parcourez les cinq étapes ci-dessous. Si vous êtes à la recherche d'idées, jetez un coup d'oeil au tableau de notre équipe Trello !

Cet article ne se retrouvera peut-être pas exactement au bon endroit, mais au moins, il est sur MDN. Si vous avez besoin de parler à quelqu'un pour le mettre au bon endroit, n'hésitez pas à nous contacter.

Étape n° 1 : écrire un résumé en deux lignes

La première phrase de l'article doit résumer le sujet que vous allez traiter, et la seconde aborder quelques particularités des éléments mis dans l'article. Par exemple :

Alors que les fichiers HTML contiennent du contenu structuré, les CSS, autre technologie majeure du Web, donneront au contenu l'apparence souhaitée. Dans cet article, nous allons détailler le fonctionnement de cette technologie et indiquer comment écrire votre propre exemple de base.

Notez comment l'exemple explique brièvement que le CSS est une technologie Web de base utilisée pour styliser les pages. C'est suffisant pour que le lecteur puisse se faire une bonne idée de ce que l'article traite.

Comme les articles du domaine d'apprentissage s'adressent principalement aux débutants, chaque article doit porter sur un sujet simple afin de ne pas noyer le lecteur sous un flot de concepts nouveaux. Si vous ne pouvez pas résumer l'article en une phrase, il se peut que vous essayiez d'en faire trop en un article !

Étape n° 2 : ajouter une boîte d'en‑tête

Ajoutez ensuite une boîte d'en‑tête pour aider les lecteurs à se repérer et savoir où ils en sont dans le processus d'apprentissage.  Voici l'exemple d'une boîte d'en‑tête issue de « Comprendre les URL et leur structure ». Vous pouvez utiliser cet article comme modèle lorsque vous écrivez le vôtre.

 

Prérequis : Vous devez au préalable savoir comment fonctionne Internet, ce qu'est un serveur web et les concepts sous-jacents aux liens sur le Web.
Objectifs : Savoir ce qu'est une URL et comprendre son rôle sur le Web.

 

Prérequis
Que doit déjà savoir le lecteur pour comprendre l'article ? Lorsque c'est possible, faites de chaque prérequis un lien vers un autre article du domaine d'apprentissage couvrant le concept (à moins qu'il ne s'agisse d'un article vraiment élémentaire qui n'exige aucune connaissance préalable).
Objectifs
Cette section décrit brièvement ce que le lecteur apprendra à la lecture de cet article. C'est un peu différent du résumé en deux lignes ; ce dernier est le condensé du sujet de l'article, tandis que les objectifs précisent ce que le lecteur peut s'attendre à apprendre à la lecture de l'article.

Note : Pour créer ce tableau, vous pouvez, soit faire un copier‑coller de l'exemple ci-dessus, soit utiliser l'outil table de l'éditeur du MDN. Si vous choisissez d'utiliser l'outil table, vous devez spécifiquement ajouter la classe CSS learn‑box en plus de la classe standard‑table par défaut. Pour ce faire, lorsque vous créez ou modifiez les propriétés de la table, allez dans le panneau "Avancé" et réglez le champ Stylesheet Classes sur « standard‑table learn‑box ».

Étape n° 3 : écrire la description compléte

Rédigez ensuite une description plus verbeuse donnant un aperçu plus complet de l'article et en soulignant les concepts les plus importants. N'oubliez pas d'expliquer pourquoi le lecteur doit prendre le temps d'apprendre ce sujet et de lire votre article !

Étape n° 4 : approfondir

Quand vous en avez fini avec tout cela, vous pouvez enfin approfondir le sujet. Vous pouvez structurer cette partie de votre article comme vous l'entendez (n'hésitez pas à consulter notre guide de style). C'est votre chance de briller ! Expliquez en détail ce à propos de quoi vous écrivez. Fournissez des liens vers la documentation de référence complète, expliquez en détail le fonctionnement de la technologie, fournissez des détails sur la syntaxe et l'utilisation, et ainsi de suite. C'est à vous de décider !

Pour vous guider, voici quelques astuces de rédaction pour les débutants :

  • Ne traitez qu'un seul sujet. Si vous pensez qu'il est nécessaire de parler d'autres sujets, cela signifie soit qu'il manque un prérequis, soit qu'il faut diviser votre article en plusieurs articles.

  • Utilisez un anglais simple. Évitez les termes techniques lorsque vous le pouvez ou, au minimum, définissez-les et, le cas échéant, établissez un lien vers les entrées correspondantes du glossaire.
  • Incluez des exemples simples pour faciliter la compréhension des concepts théoriques. Beaucoup de personnes apprennent mieux par l'exemple. Plutôt que d'écrire des articles académiques, nous voulons que les débutants comprennent facilement le texte.
  • Les aides visuelles peuvent souvent faciliter la compréhension ; elles portent des informations supplémentaires, alors n'hésitez pas à utiliser des images, des diagrammes, des vidéos et des tableaux. Si vous utilisez des diagrammes ou des graphiques contenant du texte, nous vous incitons à utiliser SVG pour que nos équipes de traducteurs puissent transcrire les éléments textuels dans les autres langues.

Jetez un coup d'œil aux premières sections de l'article Fonctions - blocs de code réutilisables pour quelques bonnes descriptions.

Étape n° 5 : fournir du matériau pour un « apprentissage actif »

Pour illustrer l'article et aider le lecteur à mieux saisir ce qu'il apprend, faites en sorte de pourvoir des exercices, des tutoriels et des tâches à accomplir. En demandant au lecteur d'utiliser et d'expérimenter activement et de façon pratique les concepts expliqués dans l'article, vous pouvez l'aider à « verrouiller » l'information dans sa tête.

Vous pouvez choisir d'incorporer les exemples directement dans la page en tant que exemples directs ou établir un lien sur eux s'ils ne fonctionnent pas sous la forme précédente. Si vous êtes intéressés par la création de ces éléments de forte valeur, veuillez lire l'article Créer un exercice interactif pour faciliter l'apprentissage du Web.

Si vous ne pouvez pas fournir de liens vers du matériel d'apprentissage actif existant (vous n'en connaissez pas ou n'avez pas le temps de les créer), vous devriez ajouter une ancre à l'article. De cette façon, d'autres contributeurs peuvent trouver des articles nécessitant du matériel d'apprentissage actif et peut-être vous aider à les trouver.

Voyez Apprentissage actif : selection des divers éléments dans le cas d'un exercice d'apprentissage actif ou Apprentissage actif : jouer dans la portée pour un autre style d'exercices : il consiste à faire télécharger localement un canevas et le modifier en suivant des étapes préétablies.

Étape n° 6 : faire revoir l'article et le mettre au menu de l'Espace d'Apprentissage

Après avoir écrit l'article, faites-le nous savoir pour que nous puissions en faire la revue et suggérer des améliorations. Encore une fois, voyez notre section Nous contacter pour connaître les meilleures façons d'entrer en contact.

Pour vraiment terminer votre article, il est nécessaire de le placer dans le menu principal de navigation de l'Espace d'Apprentissage. Ce menu est généré par la macro LearnSidebar : vous aurez besoin de privilèges spéciaux pour la modifier, donc, encore une fois, parlez en à l'une de nos équipes pour qu'il y soit ajouté.

Enfin, vous devriez ajouter l'accès au menu dans votre page — on effectue cet ajout à l'aide d'un appel à la macro {{LearnSidebar}}} dans un paragraphe au haut de votre page.

Suggestions d'articles

Vous souhaitez contribuer, mais vous n'êtes pas sûr du sujet à retenir ?

L'équipe de l'Espace d'Apprentissage tient un  tableau Trello d'idées d'articles à écrire. Vous êtes libre d'en choisir une et de vous mettre au travail !

 

 

Étiquettes et contributeurs liés au document

Étiquettes : 
Contributeurs à cette page : Dralyab
Dernière mise à jour par : Dralyab,