Revision 651721 of Write an article to help people learn about the Web

  • リビジョンの URL スラグ: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web
  • リビジョンのタイトル: Write an article to help learning the Web
  • リビジョンの ID: 651721
  • 作成日:
  • 作成者: Sheppy
  • 現行リビジョン いいえ
  • コメント

このリビジョンの内容

We present all our content specifically made for learning the Web in the MDN Learning Zone. As its primary target are beginners, we pay special attention to this area of our documentation that provides good opportunities to share your knowledge and to help newcomers become familiar with the Web.

This article explains how to write pages for the Learning Zone which introduce Web concepts to new developers.

How to write an article

To start contributing your knowledge, just hit the big green button and follow the five steps below. If you are looking for suggestions of possible themes, we maintain a list of topics at the end of this article.

{{MDNButton("Write a new learning article", "/en-US/docs/new?parent=111819")}}

Step 1: Write a one-liner

The first sentence of the article must summarize the topic covered by it.

As articles under the Learning Zone primarily target beginners, it is crucial that each covers a single straightforward topic. Being able to summarize it with one sentence is a good way to check that your writing plan fits this basic requirement.

Step 2: Add an article top box

Then add the article top box that provides fundamental information for the readers before they start reading. Its required content is:

Prerequisites
This section lists what the reader must know in order to understand the content of the article. When possible each prerequisite should be a link to another article of the Learning Zone teaching it.
Objectives
This section lists what will be learned. It is a bit different than the one-liner as the one-liner summarizes the topic of the article but the objectives section details the  achievements expected from reading the article.

Here is an example of such a top box, taken from the article "Understanding URLs and their structure". Use that article as an example to structure your own:

Prerequisites: You need to first know how the Internet works, what a Web server is and the concepts behind links on the web.
Objective: You will learn what a URL is and how it works on the Web.

Note: To produce such a table, you can copy past the above or use the table creator from the MDN editor. If you use the later way, you'll have to add a specific learn-box class in addition of the standard standard-table class. To do this, when you create the table or edit the table preferences, go to the "Advance" panel to change the classes for setting the style.

Step 3: Write a full summary for the article

This summary will roughly explain the topic of the article, providing the most important concepts and highlights of the article. Also it must tell why this topic matter. Explaining the why is a key point of any learning article, so pay attention to include this information.

Step 4: Provide a list of "Active Learning Material"

To illustrate the article and help the reader to better understand what they are learning, it is necessary to provide them exercises, tutorials and tasks to perform in order to practically manipulate the concepts explained.

As such active learning materials can be quite large, it is not recommended to create such material directly within the article, but to link to them. Creating such materials is covered in another article. If you are interested in creating some, check out the "Create an interactive exercise to help learning the web" article.

If for some reason, you are unable to provide links to existing active learning materials, do not forget to add the {{Tag("NeedsActiveLearning")}} tag to the article.

Step 5: Dig Deeper

At last, once all the above is done, you can dive deep into the topic. Feel free to structure that part as you like. You now have the opportunity to detail the full-fledged topic you are writing about. Provide links to the full reference documentation, explain how it works in details, details some syntax/usage, etc. It's up to you.

As a guidance, here are some rules of thumb to better write for beginners:

  • Focus on a single topic. If you feel you need to cover other topics, it means that there are some prerequisites missing or that the article should be split into shorter pieces.
  • Use simple English. Try to avoid technical terms as much as possible. If you can't avoid them, define the terms and/or link them to the glossary.
  • Use examples. Using straightforward examples to illustrate any theoretical knowledge make it easier to understand: many people require concrete stuff to be able to understand. Our learning articles does not require to be academic, they are required to be understandable by beginners.
  • Use and abuse schematics, illustration and picture of any kind. In many case, something visual make things easier to understand and can carry way more information than words. You can use images, videos or whatever you want to illustrate the article. If you plan to use such illustrative content with text within, we encourage you to use the {{Glossary("SVG")}} image format as it is easier to adapt when other writers will translate the article.

Suggested articles

You want to contribute but you don't know what to write about? Here's a list of suggestions. Click on one and get started :)

  1. Thinking before coding
  2. How the Internet works
  3. Understanding the difference between a web page, a web site, a web server and a search engine
  4. What is a web server?
  5. Understanding links on the web
  6. What software do I need (and what they do)?
  7. How much does it cost to do something on the web?
  8. Anatomy of a web page
  9. Beyond design, the basics of web design
  10. Understanding URLs and their structure
  11. Understanding domain name
  12. Choose, install and set up a text editor
  13. Set up a basic working environment
  14. Open a file in browser
  15. Write a simple page in HTML
  16. What are HTML tags & how to use them
  17. Upload files to a web server
  18. Checking that your web site is working properly

The articles above teach the basics, but you may wish to teach more advanced topics:

  1. What people need to see my web site?
  2. What are CSS properties and how to use them?
  3. Using CSS in a web page
  4. Basic text styling in CSS
  5. Using images
  6. What is accessibility?
  7. Design for all types of users 101
  8. Common pitfalls to avoid in web design
  9. Basics of User eXperience (UX) Design
  10. Design of navigation menus

 

 

このリビジョンのソースコード

<p>We present all our content specifically made for learning the Web in the MDN <em><a href="/en-US/docs/Learn">Learning Zone</a></em>. As its primary target are beginners, we pay special attention to this area of our documentation that provides good opportunities to share your knowledge and to help newcomers become familiar with the Web.</p>
<p><span class="seoSummary">This article explains how to write pages for the <a href="/en-US/docs/MDN/Doc_status/Learn">Learning Zone</a> which introduce Web concepts to new developers.</span></p>
<h2 id="How_to_write_an_article">How to write an article</h2>
<p>To start contributing your knowledge, <u>just hit the big green button</u> and follow the five steps below. If you are looking for suggestions of possible themes, we maintain a<a href="#Suggestions"> list of topics</a> at the end of this article.</p>
<p>{{MDNButton("Write a new learning article", "/en-US/docs/new?parent=111819")}}</p>
<h3 id="Step_1.3A_Write_a_one-liner">Step 1: Write a one-liner</h3>
<p>The first sentence of the article must summarize the topic covered by it.</p>
<p>As articles under the Learning Zone primarily target beginners, it is crucial that each covers a single straightforward topic. Being able to summarize it with one sentence is a good way to check that your writing plan fits this basic requirement.</p>
<h3 id="Step_2.3A_Add_an_article_top_box">Step 2: Add an article top box</h3>
<p>Then add the <em>article top box</em> that provides fundamental information for the readers before they start reading. Its required content is:</p>
<dl>
 <dt>
  Prerequisites</dt>
 <dd>
  This section lists what the reader must know in order to understand the content of the article. When possible each prerequisite should be a link to another article of the Learning Zone teaching it.</dd>
 <dt>
  Objectives</dt>
 <dd>
  This section lists what will be learned. It is a bit different than the one-liner as the one-liner summarizes the topic of the article but the objectives section details the&nbsp; achievements expected from reading the article.</dd>
</dl>
<p>Here is an example of such a top box, taken from the article "<a href="/en-US/docs/Learn/Understanding_URLs">Understanding URLs and their structure</a>". Use that article as an example to structure your own:</p>
<table class="standard-table learn-box">
 <tbody>
  <tr>
   <th scope="row">Prerequisites:</th>
   <td>You need to first know <a class="new" href="https://developer.mozilla.org/en-US/docs/Learn/Skills/Infrastructure/How_the_Internet_works">how the Internet works</a>, <a class="new" href="https://developer.mozilla.org/en-US/docs/Learn/Skills/Infrastructure/What_is_a_Web_server">what a Web server is</a> and <a class="new" href="https://developer.mozilla.org/en-US/docs/Learn/skills/Infrastructure/Understanding_links_on_the_web">the concepts behind links on the web</a>.</td>
  </tr>
  <tr>
   <th scope="row">Objective:</th>
   <td>You will learn what a URL is and how it works on the Web.</td>
  </tr>
 </tbody>
</table>
<div class="note">
 <p><strong>Note:</strong> To produce such a table, you can copy past the above or use the table creator from the MDN editor. If you use the later way, you'll have to add a specific <code>learn-box</code> class in addition of the standard <code>standard-table</code> class. To do this, when you create the table or edit the table preferences, go to the "Advance" panel to change the classes for setting the style.</p>
</div>
<h3 id="Step_3.3A_Write_a_full_summary_for_the_article">Step 3: Write a full summary for the article</h3>
<p>This summary will roughly explain the topic of the article, providing the most important concepts and highlights of the article. Also it must tell why this topic matter. Explaining the why is a key point of any learning article, so pay attention to include this information.</p>
<h3 id="Step_4.3A_Provide_a_list_of_.22Active_Learning_Material.22">Step 4: Provide a list of "Active Learning Material"</h3>
<p>To illustrate the article and help the reader to better understand what they are learning, it is necessary to provide them exercises, tutorials and tasks to perform in order to <em>practically</em> manipulate the concepts explained.</p>
<p>As such active learning materials can be quite large, it is not recommended to create such material directly within the article, but to link to them. Creating such materials is covered in another article. If you are interested in creating some, check out the "<a href="/en-US/docs/Project:MDN/Contributing/How_to/Create_an_interactive_exercice_to_help_learning_the_web">Create an interactive exercise to help learning the web</a>" article.</p>
<p>If for some reason, you are unable to provide links to existing active learning materials, do not forget to add the {{Tag("NeedsActiveLearning")}} tag to the article.</p>
<h3 id="Step_5.3A_Dig_Deeper">Step 5: Dig Deeper</h3>
<p>At last, once all the above is done, you can dive deep into the topic. Feel free to structure that part as you like. You now have the opportunity to detail the full-fledged topic you are writing about. Provide links to the full reference documentation, explain how it works in details, details some syntax/usage, etc. It's up to you.</p>
<p>As a guidance, here are some rules of thumb to better write for beginners:</p>
<ul>
 <li>Focus on a single topic. If you feel you need to cover other topics, it means that there are some prerequisites missing or that the article should be split into shorter pieces.</li>
 <li>Use simple English. Try to avoid technical terms as much as possible. If you can't avoid them, define the terms and/or link them to the <a href="/en-US/docs/Glossary">glossary</a>.</li>
 <li>Use examples. Using straightforward examples to illustrate any theoretical knowledge make it easier to understand: many people require concrete stuff to be able to understand. Our learning articles does not require to be academic, they are required to be understandable by beginners.</li>
 <li>Use and abuse schematics, illustration and picture of any kind. In many case, something visual make things easier to understand and can carry way more information than words. You can use images, videos or whatever you want to illustrate the article. If you plan to use such illustrative content with text within, we encourage you to use the {{Glossary("SVG")}} image format as it is easier to adapt when other writers will translate the article.</li>
</ul>
<h2 id="Suggested_articles"><a name="Suggestions"></a>Suggested articles</h2>
<p>You want to contribute but you don't know what to write about? Here's a list of suggestions. Click on one and get started :)</p>
<ol>
 <li><a href="/en-US/docs/Learn/Thinking_before_coding">Thinking before coding</a></li>
 <li><a href="/en-US/docs/Learn/How_the_Internet_works">How the Internet works</a></li>
 <li><a href="/en-US/docs/Learn/page_vs_site_vs_server_vs_search_engine">Understanding the difference between a web page, a web site, a web server and a search engine</a></li>
 <li><a href="/en-US/docs/Learn/What_is_a_web_server">What is a web server?</a></li>
 <li><a href="/en-US/docs/Learn/Understanding_links_on_the_web">Understanding links on the web</a></li>
 <li><a href="/en-US/docs/Learn/What_software_do_I_need">What software do I need (and what they do)?</a></li>
 <li><a href="/en-US/docs/Learn/How_much_does_it_cost">How much does it cost to do something on the web?</a></li>
 <li><a href="/en-US/docs/Learn/Anatomy_of_a_web_page">Anatomy of a web page</a></li>
 <li><a href="/en-US/docs/Learn/The_basics_of_web_design">Beyond design, the basics of web design</a></li>
 <li><a href="/en-US/docs/Learn/Understanding_URLs">Understanding URLs and their structure</a></li>
 <li><a href="/en-US/docs/Learn/Understanding_domain_names">Understanding domain name</a></li>
 <li><a href="/en-US/docs/Learn/Choose,_Install_and_set_up_a_text_editor">Choose, install and set up a text editor</a></li>
 <li><a href="/en-US/docs/Learn/Set_up_a_basic_working_environment">Set up a basic working environment</a></li>
 <li><a href="/en-US/docs/Learn/Open_a_file_in_a_browser">Open a file in browser</a></li>
 <li><a href="/en-US/docs/Learn/HTML/Write_a_simple_page_in_HTML">Write a simple page in HTML</a></li>
 <li><a href="/en-US/docs/Learn/HTML/HTML_tags">What are HTML tags &amp; how to use them</a></li>
 <li><a href="/en-US/docs/Learn/Upload_files_to_a_web_server">Upload files to a web server</a></li>
 <li><a href="/en-US/docs/Learn/Checking_that_your_web_site_is_working_properly">Checking that your web site is working properly</a></li>
</ol>
<p>The articles above teach the basics, but you may wish to teach more advanced topics:</p>
<ol>
 <li><a href="/en-US/docs/Learn/What_people_need_to_see_my_web_site">What people need to see my web site?</a></li>
 <li><a href="/en-US/docs/Learn/CSS/CSS_properties">What are CSS properties and how to use them?</a></li>
 <li><a href="/en-US/docs/Learn/CSS/Using_CSS_in_a_web_page">Using CSS in a web page</a></li>
 <li><a href="/en-US/docs/Learn/CSS/Basic_text_styling_in_CSS">Basic text styling in CSS</a></li>
 <li><a href="/en-US/docs/Learn/Using_images">Using images</a></li>
 <li><a href="/en-US/docs/Learn/What_is_accessibility">What is accessibility?</a></li>
 <li><a href="/en-US/docs/Learn/Design_for_all_types_of_users_101">Design for all types of users 101</a></li>
 <li><a href="/en-US/docs/Learn/Common_pitfalls_to_avoid_in_web_design">Common pitfalls to avoid in web design</a></li>
 <li><a href="/en-US/docs/Learn/Basics_of_UX_Design">Basics of User eXperience (UX) Design</a></li>
 <li><a href="/en-US/docs/Learn/Design_of_navigation_menus">Design of navigation menus</a></li>
</ol>
<p>&nbsp;</p>
<p>&nbsp;</p>
このリビジョンへ戻す