path: root/files/zh-cn/mdn/guidelines/rules_of_mdn_documenting/index.html

---
title: MDN收录规则
slug: MDN/Guidelines/Rules_Of_MDN_Documenting
translation_of: MDN/Guidelines/Does_this_belong_on_MDN
---
<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div>

<p><span class="seoSummary">如果你正准备记录什么信息，你可能想知道是否要将这些信息放入MDN。 更进一步地，你可能想在你的源代码中维护文档，并将文档写入</span><a href="https://wiki.mozilla.org/">Mozilla wiki</a>，或者写入某Git仓库的readme文件中。<span class="seoSummary"> 本文的目的是帮助你确认你的内容是否适合MDN。</span></p>

<p>文档是否应放入MDN主要取决于两点：</p>

<ul>
 <li>文档的主题（它是讲什么内容的？）</li>
 <li>文档的类型（它是什么类型的文档？）</li>
</ul>

<div class="note">
<p>注意Mozilla的 <a href="https://www.mozilla.org/en-US/about/legal/terms/mozilla/">Websites &amp; Communications Terms of Use</a> 所声明的条例在你使用MDN或对其做贡献时是生效的。检查这个文档，确保你知道在Mozilla的网站上什么是能发表的，什么是不能发表的。</p>
</div>

<h2 id="哪些话题在MDN的范畴内？">哪些话题在MDN的范畴内？</h2>

<p>MDN涉及了惊人的各种材料。总的来说，如果它是开放的面向Web的技术，或者是Mozilla的产品，我们就把它收录到MDN。但也有一小部分东西完全不属于MDN。这一节会告诉你如何确认你的文档是否属于MDN。</p>

<p>这里有一些我们涉及的事物；虽然这不是一个完整的列表，但是可以给你一个大致的印象。</p>

<h3 id="开放的Web标准与技术">开放的Web标准与技术</h3>

<p>现在Web标准文档中受关注的是那些可以被Web开发者用于创建网站与App这些大众应用的功能。这指的是那些被众多浏览器所实现，要么是被标准接受，要么是正在向标准化发展的技术。即主要关注前端Web技术。后端的技术常常在别处有它们自己的文档，MDN不会去尝试取代它们。</p>

<ul>
 <li><a href="/en-US/docs/Web/HTML" title="HTML">HTML</a></li>
 <li><a href="/en-US/docs/Web/CSS" title="CSS">CSS</a></li>
 <li><a href="/en-US/docs/Web/JavaScript" title="en/JavaScript">JavaScript</a></li>
 <li><a href="/en-US/docs/Web/SVG" title="SVG">SVG</a></li>
 <li><a href="/en-US/docs/Web/API">Web APIs</a></li>
 <li><a href="/en-US/docs/Web/API/WebGL_API" title="WebGL">WebGL</a></li>
 <li>etc.</li>
</ul>

<p>同时欢迎关注与Web开发有关的交互技术话题，比如：</p>

<ul>
 <li><a href="/en-US/docs/Web/Accessibility" title="Accessibility">Accessibility</a></li>
 <li><a href="/en-US/docs/AJAX">AJAX</a></li>
 <li><a href="/en-US/docs/Web/Guide/Graphics">Web graphics</a></li>
 <li><a href="/en-US/docs/Apps">Open web apps</a></li>
 <li><a href="/en-US/Apps/Tutorials/Games">Web-based games</a></li>
</ul>

<div class="note">
<p><strong>注意：</strong> MDN 涉及了非Mozilla但对Web开放的技术；举个例子，我们有关于WebKit格式的CSS属性的文档。</p>
</div>

<h3 id="Mozilla_产品">Mozilla 产品</h3>

<p>这个分类的文档包括如何作为开发者使用Mozilla的产品，以及如何向这些开源项目贡献。</p>

<ul>
 <li><a href="/en-US/docs/Mozilla/Firefox_OS">Firefox OS</a>

  <ul>
   <li><a href="/en-US/docs/Mozilla/Firefox_OS/Building_and_installing_Firefox_OS">Building and installing Firefox OS</a></li>
   <li><a href="en-US/Firefox_OS/Phone_guide">Firefox OS phones</a></li>
   <li><a href="en-US/Firefox_OS/Developing_Firefox_OS">Contributing to the Firefox OS project</a></li>
   <li><a href="en-US/Firefox_OS/Developing_Gaia">Developing Gaia</a></li>
   <li>etc.</li>
  </ul>
 </li>
 <li><a href="en-US/docs/Firefox">Firefox browser</a>
  <ul>
   <li><a href="/en-US/docs/Tools">Firefox Developer Tools</a></li>
   <li><a href="/en-US/docs/Mozilla/Add-ons">Add-ons</a></li>
   <li><a href="en-US/docs/Mozilla/Developer_guide/Build_Instructions">Building and configuring Firefox</a></li>
   <li>etc.</li>
  </ul>
 </li>
 <li><a href="/en-US/docs/Mozilla/Marketplace">Firefox Marketplace</a></li>
 <li><a href="/en-US/docs/Mozilla">The Mozilla platform</a>
  <ul>
   <li><a href="/en-US/docs/Mozilla/Gecko">Gecko</a></li>
   <li><a href="/en-US/docs/Mozilla/Projects/SpiderMonkey">SpiderMonkey</a></li>
   <li>etc.</li>
  </ul>
 </li>
</ul>

<h2 id="哪些话题不属于MDN？">哪些话题不属于MDN？</h2>

<p>举一些不适合MDN的话题：</p>

<ul>
 <li>仅适用于某一非Mozilla浏览器的不开放的Web技术。</li>
 <li>与Web或Mozilla产品无关的技术。</li>
 <li>面向用户的文档；对于Mozilla产品来说，这些文档应属于 <a href="https://support.mozilla.org">Mozilla 技术支持</a> 。</li>
</ul>

<h2 id="哪些类型在MDN的范畴内？">哪些类型在MDN的范畴内？</h2>

<p>In general, MDN is for <em>product</em> documentation, not for <em>project</em> or <em>process</em> documentation (except <a href="/en-US/docs/MDN">about MDN itself</a>). So, if the document is about "how to use a thing" or "how a thing works" (where the "thing" is in one of the topic categories mentioned above), then it can go on MDN. But if it about "who's working on developing a thing" or "plans for developing a thing", then it shouldn't go on MDN. In that case, if the thing is being developed under the umbrella of Mozilla, then the <a href="https://wiki.mozilla.org/Main_Page">Mozilla project wiki</a> may be a good place for it.</p>

<p>Here are some examples of types of documents that should <em>not</em> be placed on MDN<strong>:</strong></p>

<ul>
 <li>Planning documents</li>
 <li>Design documents</li>
 <li>Project proposals</li>
 <li>Specifications or standards</li>
 <li>Promotional material, advertising, or personal information{{ref("*")}}</li>
</ul>

<h2 id="Advantages_to_documenting_on_MDN">Advantages to documenting on MDN</h2>

<p>If you've determined that the documentation you want to write is appropriate in content and type for MDN, but you're still not sure whether MDN is the best place for it, read on.  There are a lot of good reasons to create documentation on MDN.</p>

<h3 id="Lots_of_writers_and_translators">Lots of writers and translators</h3>

<p>The MDN community is big. Really big. It's big in the sort of way that makes big things look small. Seriously, we have a lot of people that participate in creating and maintaining content on MDN. With writers and editors on every continent (okay, I'm not sure about Antarctica, but otherwise), there's a lot of value to the sheer volume of writers:</p>

<ul>
 <li>We have a paid staff of writers whose <strong>mission</strong> is to make sure that our content is as good as possible.</li>
 <li>We have a core community of volunteers who contribute substantial amounts of content and can help you.</li>
 <li>The MDN team can work with you to ensure that your documentation project is adequately staffed.</li>
 <li>The broader MDN community also contributes enormously; from typo fixes to editorial reviews of your content, they can save your bacon.</li>
 <li>The {{IRCLink("mdn")}} channel offers a resource where you can talk to our writing community and get their advice, or recruit help with the production of or maintenance of your content.</li>
 <li>Because we have contributors all over the world, there's always someone around, watching for problems and fixing them.</li>
 <li>Our community of volunteers includes translators for many languages, who can help localize your documentation.</li>
</ul>

<p>Do you want your development team to be entirely responsible for the production of documentation? That's likely if your documentation is maintained elsewhere.</p>

<h3 id="维护">维护</h3>

<p>Because of the sheer number of contributors, there's usually someone on hand to watch for problems with your content: from spam control to copy-editing, things can happen around the clock. Here's just a taste of what our team can do:</p>

<dl>
 <dt>Delete spam</dt>
 <dd>Spam happens. We deal with it.</dd>
 <dt>Copy editing</dt>
 <dd>You don't have to worry if your writing isn't as clear or precise as you'd like. We'll turn your prose into something other people can read.</dd>
 <dt>Consistency of style</dt>
 <dd>We'll ensure that your content is stylistically consistent not just within itself, but with the other documentation around it.</dd>
 <dt>Content management</dt>
 <dd>Our team will help ensure that the documentation is cross-linked with other relevant materials, that articles are put in the right places, and that menus and other infrastructure is built to make it easy to follow and understand.</dd>
 <dt>Site and platform maintenance</dt>
 <dd>MDN has both an IT team who keep the site up, running, and secure, and a platform development team who maintain and enhance the platform. You won't need to devote your own or additional resources to documentation infrastructure.</dd>
</dl>

<h2 id="Cases_for_documenting_elsewhere">Cases for documenting elsewhere</h2>

<p>There are also a few reasons you may be thinking about documenting your work somewhere other than MDN. Here are some of those reasons, and the pros and cons for each.</p>

<h3 id="Plans_and_processes">Plans and processes</h3>

<p>Documentation for plans, processes, and proposals should never be put on MDN. That's pretty simple. If your project is part of Mozilla, you can put them on the <a href="https://wiki.mozilla.org/Main_Page">Mozilla project wiki</a>.</p>

<h3 id="The_project_is_on_Github">The project is on Github</h3>

<p>Some of Mozilla's projects are hosted on Github, and Github offers its own wiki-like system for documentation. Some teams like to produce their documentation there. This is certainly fair and convenient if you're game to write your own docs; however, keep in mind that:</p>

<ul>
 <li>The MDN docs team will probably not be able to help you. We don't generally participate in documentation work off MDN; there are exceptions but they are rare.</li>
 <li>Cross-linking your documentation with other relevant materials may be difficult or impossible.</li>
 <li>The content will not have consistent style with other documentation.</li>
 <li>Your documentation loses discoverability by not being among other (Web or Mozilla) documentation.</li>
 <li>Github-hosted docs are generally not as attractive and/or readable as those hosted on MDN.</li>
</ul>

<p>It's possible, of course, that these things don't bother you, or aren't a problem in your situation. Some teams don't mind keeping their own docs, or are working on code that has minimal documentation needs.</p>

<h3 id="You_want_to_keep_docs_in-source">You want to keep docs in-source</h3>

<p>Some teams like to have their documentation in the source tree. This is particularly common with project internals and library projects.</p>

<p>This approach has a couple of advantages:</p>

<ul>
 <li>It lets the developers document their technology as they code it, helping to ensure that the docs stay up to date with the code.</li>
 <li>Docs can be subject to the same development and release processes as the code, including versioning.</li>
</ul>

<p>There are some drawbacks:</p>

<ul>
 <li>The MDN docs team can't help you; even if the code is within Mozilla's source repository, the system of reviews and check-ins make it impractical for the docs team to participate.</li>
 <li>You don't have easy tools for cross-linking with other relevant documentation. Cross-linking provides both context and additional important information to your readers.</li>
 <li>Your documentation loses discoverability by not being among other documentation.</li>
 <li>Even if you use conversion tools (like JavaDoc) to create Web-readable documentation, it won't be as attractive as what we can do on MDN.</li>
</ul>

<p>Still, this can be a viable option (possibly even a good option) for some types of projects, especially small ones or those that aren't expected to get much interest.</p>

<p>{{endnote("*")}} It's OK to put a limited amount of personal information on your MDN profile page. User profiles should reflect a human being, not a business or organization. A moderate degree of self-promotion is OK, but link-spamming is not. Please <em>do not </em>use your profile to upload personal photos or other irrelevant files.</p>