mozilla

Revision 651741 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: 651741
  • 作成日:
  • 作成者: Sheppy
  • 現行リビジョン いいえ
  • コメント

このリビジョンの内容

MDN's Learning Area is our home for articles that introduce Web concepts to new developers. Because its content is targeted mostly at beginners, it's a great place to share your knowledge and help newcomers become familiar with the Web. Keeping this content usable by new developers is important, so we pay special attention to it.

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

How to write a Learning Area article

To start contributing your knowledge, simply click the big green button, then follow the five steps below. If you're looking for ideas, at the end of this page we maintain a list of topics that need coverage.

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

Step 1: Write a one-liner

The first sentence of the article needs to summarize what the rest of the article is going to talk about. For example:

CSS is one of the main technologies at the heart of the Web; it takes the rough structure of the content specified by its HTML and makes it look the way you want it to look.

This is (as of the time this page was written) the first sentence of the Learning Area's article about CSS. Note how it briefly explains that CSS is a core Web technology, and that it's used to style pages. That's enough for the reader to get a pretty good idea what the page is about.

Because articles in the Learning Area primarily target beginners, it's important that each one covers a single straightforward topic, to help prevent the reader from being overwhelmed by too much new information at once. If you can't summarize the article in one sentence, you might be trying to do too much in one article!

Step 2: Add an article top box

Then add the article top box that provides fundamental information for the readers before they start reading.  Here's an example of what this box looks like, taken from the article Understanding URLs and their structure. You can use this article as an example when writing 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.

The contents of this box are:

Prerequisites
What does the reader need to know in order to understand the article's content? When possible, each prerequisite should be a link to another Learning Area article that teaches that concept.
Objectives
This section briefly states what the reader will learn over the course of the article. This is a bit different than the one-liner; the one-liner summarizes the topic of the article, while the objectives section specifically lays out the achievements the reader can expect to accomplish over the course of the article.

Note: To create this table, you can either copy and paste the example table above, or use MDN's editor's table tool. If you choose to use the table tool, you need to specifically add the learn-box CSS class in addition to the default standard-table class. To do this, when you create or edit the table's properties,, go to the "Advanced" panel and set the Stylesheet Classes field to "standard-table learn-box".

Step 3: Write a full summary

Next, write a longer summary that provides a longer overview of what the article will cover. This should highlight the most important concepts and explain to the reader why the topic is important.

Explaining the "why"—that is, why the user should take the time to read the article and learn the topic you're covering—is a key part of any article that tries to teach the reader, so be sure you include this information.

Step 4: Provide a list of "active learning materials"

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>MDN's <strong><a href="/en-US/docs/Learn">Learning Area</a></strong> is our home for articles that introduce Web concepts to new developers. Because its content is targeted mostly at beginners, it's a great place to share your knowledge and help newcomers become familiar with the Web. Keeping this content usable by new developers is important, so we pay special attention to it.</p>
<p><span class="seoSummary">This article explains how to write pages for the <a href="/en-US/docs/Learn">Learning Area</a> which introduce Web concepts to new developers.</span></p>
<h2 id="How_to_write_an_article">How to write a Learning Area article</h2>
<p>To start contributing your knowledge, simply click the big green button, then follow the five steps below. If you're looking for ideas, at the end of this page we maintain a<a href="#Suggestions"> list of topics that need coverage</a>.</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 needs to summarize what the rest of the article is going to talk about. For example:</p>
<blockquote>
 <p>CSS is one of the main technologies at the heart of the Web; it takes the rough structure of the content specified by its HTML and makes it look the way you want it to look.</p>
</blockquote>
<p>This is (as of the time this page was written) the first sentence of the Learning Area's <a href="/en-US/docs/Learn/CSS">article about CSS</a>. Note how it briefly explains that CSS is a core Web technology, and that it's used to style pages. That's enough for the reader to get a pretty good idea what the page is about.</p>
<p>Because articles in the Learning Area primarily target beginners, it's important that each one covers a single straightforward topic, to help prevent the reader from being overwhelmed by too much new information at once. If you can't summarize the article in one sentence, you might be trying to do too much in one article!</p>
<h3 id="Step_2.3A_Add_an_article_top_box">Step 2: Add an article top box</h3>
<p>Then add the <strong>article top box</strong> that provides fundamental information for the readers before they start reading.&nbsp; Here's an example of what this box looks like, taken from the article <a href="/en-US/docs/Learn/Understanding_URLs">Understanding URLs and their structure</a>. You can use this article as an example when writing 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>
<p>The contents of this box are:</p>
<dl>
 <dt>
  Prerequisites</dt>
 <dd>
  What does the reader need to know in order to understand the article's content? When possible, each prerequisite should be a link to another Learning Area article that teaches that concept.</dd>
 <dt>
  Objectives</dt>
 <dd>
  This section briefly states what the reader will learn over the course of the article. This is a bit different than the one-liner; the one-liner summarizes the topic of the article, while the objectives section specifically lays out the achievements the reader can expect to accomplish over the course of the article.</dd>
</dl>
<div class="note">
 <p><strong>Note:</strong> To create this table, you can either copy and paste the example table above, or use MDN's editor's <a href="/en-US/docs/MDN/Contribute/Editor/Tables">table tool</a>. If you choose to use the table tool, you need to specifically add the <code>learn-box</code> CSS class in addition to the default <code>standard-table</code> class. To do this, when you create or edit the table's properties,, go to the "Advanced" panel and set the <strong>Stylesheet Classes</strong> field to "<code>standard-table learn-box</code>".</p>
</div>
<h3 id="Step_3.3A_Write_a_full_summary_for_the_article">Step 3: Write a full summary</h3>
<p>Next, write a longer summary that provides a longer overview of what the article will cover. This should highlight the most important concepts and explain to the reader why the topic is important.</p>
<p>Explaining the "why"—that is, why the user should take the time to read the article and learn the topic you're covering—is a key part of any article that tries to teach the reader, so be sure you 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 materials"</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>
このリビジョンへ戻す