How to write an article to help people learn about the Web

MDN's Learning Area is our home for articles that introduce Web concepts to new developers. Because its content mostly targets beginners, it's a great place to share your knowledge and help newcomers get to know the Web. It's important to make sure new developers can follow this content, so we pay special attention to it.

This article explains how to write pages for the Learning Area.

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, please take a look at the our team Trello board!

Step 1: Write a one-liner

Your article's first sentence needs to summarize what you're going to cover. For example:

Whereas HTML files contain structured content, CSS, another major Web technology, makes the content look the way you want.

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

Because Learning Area articles primarily target beginners, each article should cover one straightforward topic so as not to overwhelm the reader with too much new information. If you can't summarize the article in one sentence, you might be trying to do too much in one article!

Step 2: Add a top box

Then add a top box to help readers get their bearings as to where they are in the learning process.  Here's an example of a top box from "Understanding URLs and their structure". You can use this article as an model 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.
Prerequisites
What must the reader already know to follow the article? When possible, make each prerequisite a link to another Learning Area article covering the concept (unless it's a really basic article that doesn't require prior knowledge).
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 what 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 more thorough overview of the article highlighting the most important concepts. Don't forget to explain why the reader should take the time to learn this topic and read your article!

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

To illustrate the article and help the reader better understand what they're learning, be sure to provide exercises, tutorials, and tasks to accomplish. By having them actively and practically using and experimenting with the concepts your article explains, you can help "lock" the information into their brains.

Because these active learning materials can be quite large, you should generally link to them rather than including them right in the article. If you're interested in helping create these valuable materials, please read the article Create an interactive exercise to help learning the Web.

If you can't provide links to existing active learning materials (you don't know of any or don't have time to create them), you should add the tag to the article. That way other contributors can find articles that need active learning materials and perhaps help you come up with them.

Step 5: Dig deeper

When you're done with all that, you can finally dive deeply into the topic. You can structure this part of your article however you like (although feel free to consult our style guide). This is your chance to shine! Go into detail explaining the topic you're writing about. Provide links to the full reference documentation, explain how the technology works in detail, provide syntax and usage details, and so forth. It's up to you!

As a guide, here are some writing tips for beginners:

  • Focus on a single topic. If you feel like you need to cover other topics, it means either you're missing a prerequisite article, or you need to break up your article into more than one.
  • Use simple English. Avoid technical terms when you can, or at least define them and link to their glossary entries where applicable.
  • Include straightforward examples to make the theoretical concepts easier to grasp. Many people learn best by example. Rather than writing academic papers, we want beginners to follow the text readily.
  • Visual aids often can make things easier to digest and carry extra information, so feel free to use images, diagrams, videos, and tables. If you're using diagrams or charts that include text, we encourage you to use SVG so our translation teams can localize the text.

Suggested articles

So you want to contribute but you're not sure what to write about?

The Learning Area team maintains a Trello board with ideas of articles to write. Feel free to pick one and get to work!

 

 

Document Tags and Contributors

 Contributors to this page: jswisher, Andrew_Pfeiffer, Jeremie, Sheppy, teoli
 Last updated by: jswisher,