MDN Web 文档的收录标准

MDN Web 文档的使命是记录由可靠的标准机构发布的规范中的 Web 标准技术，并且这些技术至少在一个稳定版本的浏览器中得到支持。这些标准表明了整个 Web 行业的兴趣、稳定性保证和“实现意愿”。因此，我们认为这些技术是我们花费时间和精力记录的安全选择。任何早于此阶段的 Web 技术或特性都可能因缺乏兴趣而被取消，或者可能非常不稳定，以致于可能会发生重大变化，这将不必要地涉及大量内容的重写（我们尽可能避免这种情况）。

非 Web 标准技术是指不符合上述标准的技术。我们通常不会考虑将其收录到 MDN Web 文档中。

我们的使命是“为开放 Web 上的开发者提供他们所需的信息，以便轻松构建项目”。这表明，我们应该考虑记录对 Web 开发者有用的技术，即使它们不是开放 Web 标准、标准轨道上的技术，等等。

如果你想考虑将非 Web 标准技术收录到 MDN Web 文档中，你应该确保它符合以下标准。

技术应满足以下标准，才能被视为适合收录到 MDN Web 文档中。

在 MDN Web 文档，我们支持开放技术。我们不支持由单一实体控制、不对任何利益相关方提供贡献机会、不能跨平台和系统进行互操作的封闭的技术生态系统。我们相信，开放创造的技术更有益于每个人。

我们的核心职责是 Web 标准技术；记录与 Web 或 Web 技术无关，或者对 Web 开发者没有任何兴趣的技术是没有意义的。

我们不想花时间记录一个行业不感兴趣且未被采纳的技术。可能只是因为从现在就开始记录这项技术还为时过早，我们可以考虑在未来将其记录到 MDN Web 文档中。

与上述观点相关的是，我们也不想花时间记录已经处于生命周期的后期，并且已经显示出兴趣衰减迹象的技术。

现有许多库和框架，它们不是 Web 标准，但是建立在 Web 技术之上，并且在 Web 行业中非常流行。我们不会记录其中的任何一个，因为一般来说，它们都已经建立了文档资源。与流行框架的官方资源竞争是愚蠢的——这样做会浪费时间，而且可能会让试图学习该技术的开发者感到困惑。

MDN Web 文档团队专注于记录开放 Web 平台。如果你想让 MDN Web 文档考虑记录某项技术，你需要组建一个愿意编写文档并在完成后维护文档的社区。我们团队很乐意在这种情况下提供包括编辑和反馈在内的指导，但我们没有除此以外的更多资源。

如果一项技术看起来很适合在 MDN Web 文档上记录，你可以在 GitHub 社区讨论上发起讨论，以提议并讨论是否将该技术收录到 MDN Web 文档中。本节描述了该提议应包含的内容。

要根据具体情况考虑是否将技术收录到 MDN Web 文档中。你需要提交一个标题为“Proposal for documenting a new technology on MDN Web Docs”（在 MDN Web 文档上记录新技术的提议）的提议，以供审议。我们需要你提供以下信息：

• 技术及其核心目的/用例和目标开发者受众。
• 对该技术最感兴趣的行业或社区有哪些？
  • 有很多 Web 开发者在使用它吗？行业采用情况如何？
  • 有很多 Web 开发者想要或需要这些信息吗？
  • 这些信息的目标受众规模如何？如果有支持的统计数据，那么请提供。
• 该技术与核心 Web 技术和 Web 浏览器有何关联？有用的细节包括：
  • 它是否使用 HTML 和 CSS，但通常不输出到 Web？
  • Web 浏览器是否需要通过 polyfill 来支持它？
• 已有哪些文档或资源涵盖了该技术？
• 需要向 MDN Web 文档添加多少文档？
  • 列出元素/方法/属性等的指南、教程、参考页面的预期数量。
  • 提供高级目录。
  • 除了基本文档页面之外，提及你认为可能需要的“高级”特性。你是否希望包含嵌入视频、交互式代码示例等？
• 编写文档的人员？他们是谁，以及为什么他们适合这份工作？
• 文档的维护方式是什么？

在这个阶段，你不需要向我们提供数百页的详细信息（事实上，我们更希望你不要这样做）。对于上述的每一点，用几段话就足够了。

我们将考虑你在提议中提交的技术和信息，并给出以下回复之一：

• 不予采纳：我们认为这不符合 MDN Web 文档的收录标准。
• 可能采纳：我们不确定它是否适合在 MDN Web 文档上记录，并且想要进一步提问。
• 采纳：我们认为它适合在 MDN Web 文档上记录。

如果该技术是一个很好的候选项，团队将协助你开始编写文档。

如果 MDN Web 文档接受了你选择的技术，那么下一步就是开始编写文档。

为确保你在 MDN Web 文档上记录新技术的项目取得成功，我们需要你做好以下准备：

• 专门的团队
• 项目计划和路线图
• 编写指南和标准
• 直观的文档结构
• 维护计划

确保你有一个专门的团队来编写初始文档，并在未来进行必要的更新。

考虑有多少工作量，以及可能需要多少人来完成。

• 如果这是一个大型项目，你可能需要一个由几位作者、一位检查工作是否在技术上准确的技术审阅者、一位清理内容的文字编辑、几位编写代码示例的人员等组成的团队，你会从中受益。
• 如果是一个小项目，你可能会有一两个人承担多个角色。只要对你有用，你想如何建立团队都可以。

MDN Web 文档团队中的成员将被分配到你的项目中，以提供来自 MDN Web 文档团队的指导。

你应该指定一名（或两名）团队负责人，他们可以与 MDN Web 文档团队成员联络。

MDN Web 文档的代表将帮助你的团队中的每个人获得在 GitHub MDN 组织中工作所需的权限。

创建一个项目计划——任务、预计完成日期和里程碑，以确保你在稳步推进。

如果是项目很大，你应该考虑指定一个团队成员作为项目经理。你还应该考虑编写子项目计划，以发布最小可发布文档集合（最小可行产品）；之后可以进行进一步的添加。

如果文档记录项目很小，你仍然需要记录已完成和未完成的工作，文档记录的每一部分处于什么阶段（例如，未开始、进行中、已撰写草稿、已审核、已完成），以及谁在做什么工作。

这些指南说明了我们期望如何为 MDN Web 文档编写文档。

如果你对正在编写的文档有其他指南，我们希望将其添加到本指南中，并确保其内容是最新的。

就标准而言，我们期望你保证合理的写作质量，以便你的文档能够保留在 MDN Web 文档上。MDN Web 文档的代表将与你合作，让你明确知道期望的内容。

如果你已经通过了提议提交流程，那么你应该已经有了一个粗略的大纲，知道你将为这项技术编写的内容。此时，你应该将其细化为站点结构计划：考虑文档层次结构将是什么样子，以及所有内容如何组织和链接在一起。

每个项目不尽相同，但我们大致建议如下：

着陆页
|
------参考
      |
      --------元素
      |
      --------方法
      |
      --------其他参考页类型？
|
------指南/教程
|
------示例

每个项目中使用的每个页面类型都应该有一个页面模板，供其他人从中复制结构。你应该尽早决定这些。

请参阅我们关于页面类型的部分。如果需要添加，请与你的 MDN Web 文档代表联系。

该技术的文档需要维护，以将其保留在 MDN Web 文档上：

• MDN Web 文档的内容和文件存储在 GitHub 上。当其他人对你的技术文档进行更改时，你的团队成员需要审查这些更改，以确保内容仍然良好。你可以通过 GitHub 的通知功能跟踪打开的拉取请求（PR）。
• 当技术发生变化需要更新文档时，你的团队需要在保持与原始文档相同的标准的情况下，对文档进行适当的更新。

如果在六个月的时间内没有观察到积极的变化，并且文档似乎处于以下任何状态：

• 陈旧或无人维护
• 在没有完成的情况下停滞不前
• 质量低下
• 逐渐过时

那么我们将认为该技术的文档已死。在经过 MDN Web 文档团队代表与你的团队的讨论后，文档将被删除。

我们希望你能理解，我们需要严格对待这些问题——我们不能让网站充斥着质量低下、不完整或过时的文档。