MDN Web 文档的收录标准

本文详细描述了 MDN Web 文档收录内容的标准,以及申请记录新的文档的流程,以及对申请方的期望和指南。

这是针对较大的项目的。如果要建议新增页面或文章,请参阅“MDN 收录规则”页面上的建议内容部分。

Web 标准技术

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

非 Web 标准技术

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

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

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

MDN Web 文档的收录标准

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

开放且非专有

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

与 Web 或 Web 技术相关

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

存在兴趣和被采纳的迹象

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

没有显示出被弃用或被取代的迹象

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

在其他地方没有已建立的文档资源

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

有愿意为之编写和维护文档的社区

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

备注:MDN Web 文档的工作是在 GitHub 上“公开”进行的。你的团队应该熟悉 git 和 GitHub,并且习惯于在开源项目中工作。

选择新技术的流程

如果一项技术看起来很适合在 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 文档主要是英文站点(en-US)。你的项目的主要语言应该是美式英语。

等待回复

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

  • 不予采纳:我们认为这不符合 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 文档团队代表与你的团队的讨论后,文档将被删除。

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