MDN Web 文档收录标准

MDN Web 文档的目标是记录由可靠的标准机构发布的规范中定义的，并且至少在一个稳定浏览器中受支持的 Web 标准技术。这些标准表明了整个 Web 行业对这些技术的足够兴趣、稳定性和“实施意图”。因此，我们认为这些技术是我们花费时间和精力记录的安全选择。在此之前，Web 技术或功能可能会因缺乏兴趣而被取消，或者可能不稳定而发生重大变化，这将不必要地导致大量重写（我们尽量避免这种情况）。

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

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

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

技术应满足此处描述的标准，才能被考虑收录到 MDN Web 文档中。

在 MDN Web 文档中，我们支持开放技术。我们不支持由单个实体控制的封闭技术生态系统，这些生态系统不允许任何感兴趣的各方进行贡献，并且在多个平台和系统之间无法互操作。我们相信，当技术在公开环境中创建时，它才能更好地为所有人服务。

我们的核心职责是 Web 标准技术；记录与 Web 无关或对 Web 开发人员没有吸引力的技术毫无意义。

我们不想花费时间记录一项行业没有表现出兴趣和采用的迹象的技术。它可能只是现在记录该技术还为时过早，我们将来可能会考虑将其收录到 MDN Web 文档中。

与上述要点相关，我们也不想花费时间记录一项生命周期已晚且已显示出兴趣下降迹象的技术。

现存许多库和框架，它们不是 Web 标准，但构建在 Web 技术之上，并且在 Web 行业中非常流行。我们不记录这些内容，因为通常它们都有现成的文档资源。与流行框架的官方资源竞争是愚蠢的——这样做会浪费时间，并且可能会让试图学习该技术的开发人员感到困惑。

MDN Web 文档团队专注于记录开放的 Web 平台。如果您希望将此领域的某项技术纳入 MDN Web 文档，您需要组建一个愿意编写文档并在完成之后维护文档的社区。我们的团队很乐意在这些情况下提供指导，包括编辑和反馈，但我们没有更多资源。

如果一项技术看起来像一个适合收录到 MDN Web 文档中的候选者，您可以开始在GitHub 社区讨论中进行讨论，以提出并讨论将该技术纳入 MDN Web 文档。本节描述了提案应包含哪些内容。

技术将根据具体情况考虑是否收录到 MDN Web 文档中。为了获得考虑，您需要提交一个标题为“关于在 MDN Web 文档中记录新技术的提案”的提案。我们需要您在提案中提供以下信息

• 技术、其核心目的/用例和目标开发人员群体。
• 围绕该技术有哪些行业或社区关注度？
  • 许多 Web 开发人员是否在使用它？行业采用率如何？
  • 许多 Web 开发人员是否希望或需要这些信息？
  • 这些信息的受众规模有多大？如果您有相关数据，请提供支持统计数据。
• 该技术如何与核心 Web 技术和 Web 浏览器相关？有用的详细信息包括
  • 它是否使用 HTML 和 CSS，但通常不会输出到 Web 上？
  • 它是否通过 polyfill 在 Web 浏览器中受支持？
• 哪些文档或资源已涵盖该技术？
• 需要向 MDN Web 文档添加多少文档？
  • 列出预期元素/方法/属性等的指南、教程、参考页面数量。
  • 提供高级目录。
  • 提及您认为此资源可能需要的“高级”功能，超出基本文档页面。您是否期望包含嵌入式视频、交互式代码示例等？
• 谁将编写文档？他们是谁，为什么适合这项工作？
• 文档将如何维护？

您无需在此阶段提供数百页的详细内容（事实上，我们更希望您不要这样做）。关于每个要点的一两段话就足够了。

我们将考虑您在提案中提交的技术和信息，并回复以下答案之一

• 否：我们认为这并不符合 MDN Web 文档的收录标准。
• 也许：我们不确定它是否适合收录到 MDN Web 文档中，想进一步了解一些问题。
• 是：我们认为它适合收录到 MDN Web 文档中。

如果该技术是合适的候选者，团队将协助您开始编写文档。

如果您的所选技术被接受收录到 MDN Web 文档中，下一步就是开始编写文档。

为了确保您在 MDN Web 文档中记录新技术的项目取得成功，您需要做好以下准备

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

确保您有一个专门的团队，他们将负责编写初始文档以及将来维护文档所需的更新。

仔细考虑工作量以及可能需要多少人。

• 如果这是一个大型项目，您可能受益于拥有几位撰稿人、一位技术审阅者来检查工作是否在技术上准确、一位校对员来润色语言、一位编写代码示例的人员等。
• 在一个较小的项目中，您可能只有一两个人承担多个角色。无论您想如何组建团队都可以，只要适合您即可。

MDN Web 文档团队的一名成员将被分配到您的项目中，为 MDN Web 文档方面提供指导。

您应该指定一位（或两位）团队负责人，他们可以与 MDN Web 文档团队成员进行沟通。

MDN Web Docs 代表会帮助您的团队成员获取所需的权限，以便在GitHub 上的 MDN 组织中工作。

为项目制定计划——任务、估计完成日期以及您希望跟踪的里程碑，以确保您取得稳定进展。

如果项目较大，您应该考虑指定团队成员之一担任项目经理。您还应该考虑为初始版本编写子项目计划，该计划包含一组发布后有用的最小文档集（最小可行产品）；稍后您可以继续添加更多内容。

如果文档项目较小，您仍然需要记录已完成和未完成的工作，文档每个部分的阶段（例如，未开始、进行中、已编写草稿、已审阅、已完成）以及谁在处理什么。

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

如果您对正在编写的文档有其他指南，我们希望将此指南添加到其中并保持更新。

在标准方面，您需要保持文档的合理写作质量，以便将其保留在 MDN Web Docs 上。您的 MDN Web Docs 代表将与您合作，让您清楚了解预期。

如果您完成了提案提交流程，那么您应该已经对要为这项技术编写的内容有一个大致的概述。此时，您应该将其细化为站点结构计划：思考文档层次结构将是什么以及所有内容将如何拟合和链接在一起。

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

Landing page
|
------Reference
      |
      --------Elements
      |
      --------Methods
      |
      --------Other reference page type(s)?
|
------Guides/tutorials
|
------Examples

您将在项目中使用的每种页面类型都应有一个页面模板，以便其他人从中复制结构。您应该尽早确定这些模板。

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

此技术的文档需要维护才能保留在 MDN Web Docs 上

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

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

• 陈旧或未维护
• 停滞不前，未完成
• 质量低下
• 即将过时

那么此技术的文档将被视为失效。在您的团队和 MDN Web Docs 团队代表之间进行讨论后，该文档将被删除。

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