Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Revision 1063546 of How to contribute to docs that are currently needed

  • Revision slug: Contribute_to_docs_that_are_currently_needed
  • Revision title: How to contribute to docs that are currently needed
  • Revision id: 1063546
  • Created:
  • Creator: salman-shah
  • Is current revision? No
  • Comment

Revision Content

If you're interested in contributing to MDN, and you're looking for topics to write new content about, that's a rather open-ended process, with several stages:

  1. Find a topic that is needed and that interests you.
  2. Talk to MDN writers to let them know that you're interested in working on the topic. You don't need their approval to work on a topic, but it's a good idea to coordinate with other people who are working on related things.
  3. If necessary, get in touch with technical experts who can help you with the technical content.
  4. Write the article or articles.
  5. Ask for technical review.
  6. Ask for editorial review.

Some of these phases are iterative; for example, you may have several conversations with MDN staff writers or technical experts, at various points in the process of writing and reviewing one or more articles about a topic.

Find a topic

There are a few places to look for topics to work on.

Documentation requests

When someone submits a request for new or updated docs on MDN, the staff team reviews it, determines whether the work is suitable to be done by a new contributor, and assigns a mentor to help. See How to resolve a mentored documentation request for details of how to find and pursue one of these requests.

Prioritized doc topics

The MDN staff writers organize their work in agile sprints. You can view the team's Kanban board to see the user stories that are currently prioritized. The items in the Ready column are fully fleshed out with tasks and acceptance criteria. The items in the New column are less fleshed-out, but are still considered important in the near future. If you're interested in contributing to any of these items, see the Talk to MDN writers section to start a conversation about it.

dev-doc-needed bugs

Some Mozilla code changes are flagged in Bugzilla as needing developer documentation, using the "dev-doc-needed" keyword. These issues are usually specific to Mozilla product code, and require some familiarity with the codebase to address. See How to resolve a dev-doc-needed bug for details.

Talk to MDN writers

The main channel for discussion of MDN content is the dev-mdc mailing list. (You can also view the archives on the web at mozilla.dev.mdc.) Even if you know the name of an individual who is concerned with the topic you're interested in, it's a good idea to post any discussions on dev-mdc, so that they can be shared by the rest of the community. If you don't know the name of an individual to ask, posting an inquiry on dev-mdc is a good way to find out who to talk to.

If you're working on a mentored documentation request, you can interact with the mentor via comments in the bug record; in this case, Bugzilla is the preferred communication channel, so that all activity around the request is captured in one place.

Talk to technical experts

In order to start documenting a topic, you may need to find some technical experts on that topic. (If you are a technical expert on the topic you're documenting, either this step does not apply, or you probably already know who else to talk to.) As part of your conversations with other MDN writers, be sure to ask for pointers or introductions to technical experts.

When approaching technical experts for information, try to make it easy and efficient for them to help you. Ask if there is existing information in Bugzilla records, mailing list archives, standards specifications, test cases, and so on, if you weren't able to get these leads from MDN writers. After you have done your best to make sense of the existing information, bring specific questions to the expert. Questions like "The spec talks about X, but doesn't seem to address Y" are easier for an expert to respond to than "I'm documenting the FooBar API. Can you tell me about it?"

Write the article

For the mechanics of creating an article, see How to create and edit pages. Depending on the type of article, we might have more specific guidance:

Ask for technical review

If you haven't found a technical expert yet (or even if you have), see How to recruit a technical reviewer.

Be sure that the Technical review flag is ticked. In the MDN Editor UI, it appears near the bottom under Review needed?

Ask for editorial review

You can ask for an editorial review by posting on dev-mdc. Be sure that the Editorial review flag is ticked. In the MDN Editor UI, it appears near the bottom under Review needed?

Revision Source

<p>If you're interested in contributing to MDN, and you're looking for topics to write new content about, that's a rather open-ended process, with several stages:</p>

<ol>
 <li><a href="#Find_a_topic">Find a topic</a> that is needed and that interests you.</li>
 <li><a href="#Talk_to_MDN_writers">Talk to MDN writers</a> to let them know that you're interested in working on the topic. You don't need their approval to work on a topic, but it's a good idea to coordinate with other people who are working on related things.</li>
 <li>If necessary, <a href="#Talk_to_technical_experts">get in touch with technical experts</a> who can help you with the technical content.</li>
 <li><a href="#Write_the_article">Write the article</a> or articles.</li>
 <li><a href="#Ask_for_technical_review">Ask for technical review</a>.</li>
 <li><a href="#Ask_for_editorial_review">Ask for editorial review</a>.</li>
</ol>

<p>Some of these phases are iterative; for example, you may have several conversations with MDN staff writers or technical experts, at various points in the process of writing and reviewing one or more articles about a topic.</p>

<h3 id="Find_a_topic">Find a topic</h3>

<p>There are a few places to look for topics to work on.</p>

<h4 id="Documentation_requests">Documentation requests</h4>

<p>When someone submits a request for new or updated docs on MDN, the staff team reviews it, determines whether the work is suitable to be done by a new contributor, and assigns a mentor to help. See <a href="/en-US/docs/MDN/Contribute/Howto/Resolve_a_mentored_developer_doc_request">How to resolve a mentored documentation request</a> for details of how to find and pursue one of these requests.</p>

<h4 id="Prioritized_doc_topics">Prioritized doc topics</h4>

<p>The MDN staff writers organize their work in <a href="https://en.wikipedia.org/wiki/Sprint_%28software_development%29">agile sprints</a>. You can view the team's <a href="https://tree.taiga.io/project/viya-mdn-durable-team/kanban">Kanban board</a> to see the <a href="https://en.wikipedia.org/wiki/User_story">user stories</a> that are currently prioritized. The items in the Ready column are fully fleshed out with tasks and acceptance criteria. The items in the New column are less fleshed-out, but are still considered important in the near future. If you're interested in contributing to any of these items, see the <a href="#">Talk to MDN writers</a> section to start a conversation about it.</p>

<h4 id="dev-doc-needed_bugs">dev-doc-needed bugs</h4>

<p>Some Mozilla code changes are flagged in Bugzilla as needing developer documentation, using the "dev-doc-needed" keyword. These issues are usually specific to Mozilla product code, and require some familiarity with the codebase to address. See <a href="/en-US/docs/MDN/Contribute/Howto/Resolve_a_dev-doc-needed_bug">How to resolve a dev-doc-needed bug</a> for details.</p>

<h3 id="Talk_to_MDN_writers">Talk to MDN writers</h3>

<p>The main channel for discussion of MDN content is the <a href="https://lists.mozilla.org/listinfo/dev-mdc">dev-mdc</a> mailing list. (You can also view the archives on the web at <a href="https://groups.google.com/forum/#!forum/mozilla.dev.mdc">mozilla.dev.mdc</a>.) Even if you know the name of an individual who is concerned with the topic you're interested in, it's a good idea to post any discussions on dev-mdc, so that they can be shared by the rest of the community. If you don't know the name of an individual to ask, posting an inquiry on dev-mdc is a good way to find out who to talk to.</p>

<p>If you're working on a mentored documentation request, you can interact with the mentor via comments in the bug record; in this case, Bugzilla is the preferred communication channel, so that all activity around the request is captured in one place.</p>

<h3 id="Talk_to_technical_experts">Talk to technical experts</h3>

<p>In order to start documenting a topic, you may need to find some technical experts on that topic. (If you <em>are</em> a technical expert on the topic you're documenting, either this step does not apply, or you probably already know who else to talk to.) As part of your conversations with other MDN writers, be sure to ask for pointers or introductions to technical experts.</p>

<p>When approaching technical experts for information, try to make it easy and efficient for them to help you. Ask if there is existing information in Bugzilla records, mailing list archives, standards specifications, test cases, and so on, if you weren't able to get these leads from MDN writers. After you have done your best to make sense of the existing information, bring specific questions to the expert. Questions like "The spec talks about X, but doesn't seem to address Y" are easier for an expert to respond to than "I'm documenting the FooBar API. Can you tell me about it?"</p>

<h3 id="Write_the_article">Write the article</h3>

<p>For the mechanics of creating an article, see <a href="/en-US/docs/MDN/Contribute/Howto/Create_and_edit_pages">How to create and edit pages</a>. Depending on the type of article, we might have more specific guidance:</p>

<ul>
 <li><a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference">How to write an API reference</a></li>
 <li><a href="/en-US/docs/MDN/Contribute/Howto/Write_interface_reference_documentation">How to write Mozilla interface reference documentation</a></li>
 <li><a href="/en-US/docs/MDN/Contribute/Howto/Document_a_CSS_property">How to document a CSS property</a></li>
 <li><a href="/en-US/docs/MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web">How to write an article to help people learn about the Web</a></li>
 <li><a href="/en-US/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary">How to write and reference a Glossary entry</a></li>
 <li><a href="/en-US/docs/MDN/Contribute/Howto/Create_learning_pathways">How to create learning pathways</a></li>
</ul>

<h3 id="Ask_for_technical_review">Ask for technical review</h3>

<p>If you haven't found a technical expert yet (or even if you have), see <a href="/en-US/docs/MDN/Contribute/Howto/Recruit_a_technical_reviewer">How to recruit a technical reviewer</a>.</p>

<p>Be sure that the <strong>Technical</strong> review flag is ticked. In the MDN Editor UI, it appears near the bottom under <strong>Review needed?</strong></p>

<h3 id="Ask_for_editorial_review"><strong>Ask for editorial review</strong></h3>

<p>You can ask for an editorial review by posting on dev-mdc. Be sure that the <strong>Editorial</strong> review flag is ticked. In the MDN Editor UI, it appears near the bottom under <strong>Review needed?</strong></p>
Revert to this revision