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!
This article might not end up in exactly the right place, but at least it's on MDN. If you need to talk to someone about getting it moved to the right place, please Contact us.
Step 1: Write a two-liner
Your article's first sentence needs to summarize what subject you're going to cover, and the second one should go into a few more specifics of the items that you'd put in the article. For example:
Whereas HTML files contain structured content, CSS, another major Web technology, makes the content look the way you want. In this article we are going to cover how this technology works, and how to write your own basic example.
Note how the example 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 description
Next, write a longer description 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: 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.
Have a look at the first few sections of our Functions — reusable blocks of code article for some good descriptive sections.
Step 5: Provide "active learning" material
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.
You can choose to include the examples directly in the page as live samples, or link to them if they don't really work as a live sample. 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 NeedsActiveLearning to the article. That way other contributors can find articles that need active learning materials and perhaps help you come up with them.
Have a look at Active learning: selecting different elements for a live interactive learning exercise, or Active learning: Playing with scope for a different style of exercise that calls upon them to download a template locally and modify it following the provided steps.
Step 6: Get the article reviewed, and put into the Learning Area navigation menu
After you've written your article, let us know so we can have a look at it, do a review, and suggest improvements. Again, see our Contact us section for the best ways to get in touch.
Another part finalizing your article is to put it in the Learning Area main navigation menu. This menu is generated by the LearnSidebar macro, which you need special privileges to edit, so again, talk ot one of our team about getting it added.
You should at least add it to your page — this is done by adding the macro call {{LearnSidebar}} into a paragraph at the top of your page.
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!