MDN Web Docs 内容收录标准

Web 标准技术

MDN Web Docs 的宗旨是记录在可靠的标准机构发布的规范中、并且至少在一个稳定浏览器中得到支持的 Web 标准技术。这些标准表明了 Web 行业对该技术的足够兴趣、稳定性和“实现意向”。因此，我们认为这些技术值得我们花费时间和精力去记录。过早记录一项 Web 技术或功能可能会因缺乏兴趣而被取消，或者可能不稳定而发生重大变化，这将不必要地导致大量重写（我们尽量避免这种情况）。

非 Web 标准技术

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

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

如果您希望考虑将非 Web 标准技术收录到 MDN Web Docs 中，您应确保它符合以下标准。

技术名称、核心用途/用例以及目标开发者受众。
围绕该技术有哪些行业或社区的关注度？
- 是否有大量 Web 开发者在使用它？行业采纳情况如何？
- 是否有大量 Web 开发者想要或需要这些信息？
- 此信息的目标受众规模有多大？如果可能，请提供支持性统计数据。
该技术与核心 Web 技术和 Web 浏览器有何关联？有用的细节包括：
- 是否使用 HTML 和 CSS，但通常不输出到 Web？
- 是否通过 polyfill 在 Web 浏览器中得到支持？
目前有哪些文档或资源涵盖该技术？
需要在 MDN Web Docs 中添加多少文档？
- 列出预期的指南、教程、元素/方法/属性参考页等的数量。
- 提供一个高层级的目录。
- 提及您认为此资源除了基础文档页面外，可能还需要包含哪些“高级”功能？您是否期望包含嵌入式视频、交互式代码示例等？
谁将编写文档？他们是谁，为什么适合这项工作？
文档将如何维护？

在此阶段，您无需向我们提供数百页的详细信息（事实上，我们更希望您不要这样做）。对以上每一点进行几段描述已经足够。

注意： MDN Web Docs 主要是一个英文网站 (en-US)。您项目的主要语言应为美式英语。

等待回复

我们将审阅技术和您在提案中提供的信息，并回复以下答案之一：

否：我们认为它不符合在 MDN Web Docs 中记录的标准。
可能：我们不确定它是否适合在 MDN Web Docs 中记录，并希望提出一些进一步的问题。
是：我们认为将其收录到 MDN Web Docs 中是合适的。

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

记录新技术的项目指南

如果您的选定技术已被接受在 MDN Web Docs 中进行记录，下一步就是开始。

为了确保您在 MDN Web Docs 中记录新技术的项目成功，我们需要您具备以下条件：

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

专门的团队

请确保您有一个专门的团队，负责编写初始文档并进行未来的维护和更新。

请考虑工作量以及您可能需要多少人。

如果这是一个大型项目，您可能需要几名作者、一名技术审阅员来检查技术准确性、一名编辑来润色语言、一名代码示例编写者等等。
在一个小型项目中，您可能只需要一两个人承担多个角色。您如何组建团队都可以，只要适合您即可。

MDN Web Docs 团队将为您分配一名成员，负责提供 MDN Web Docs 方面的指导。

您应指定一到两名团队负责人，他们可以与 MDN Web Docs 团队成员进行沟通。

MDN Web Docs 代表将协助为您的团队成员获取在 GitHub 上的 MDN 组织中工作的必要权限。

项目计划和路线图

为项目创建计划——任务、预计完成日期以及您想要跟踪以确保稳步进展的里程碑。

如果项目很大，您应该考虑指定一名团队成员担任项目经理。您还应该考虑为初始发布编写一个子项目计划，该计划包含可发布的最低限度文档（一个最小可行产品）；之后您可以进行进一步的补充。

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

写作指南和标准

这些指南说明了我们期望 MDN Web Docs 文档的编写方式。

如果您有关于您正在编写的文档的额外指南，我们希望此指南能够得到补充并保持更新。

在标准方面，您需要保持合理的写作质量，以使您的文档能够保留在 MDN Web Docs 上。您的 MDN Web Docs 代表将与您合作，明确您需要做什么。

直观的文档结构

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

每个项目都不同，但我们建议以下目录结构：

├── Guides
│   ├── guide_one
│   ├── guide_two
│   └── index.md
├── index.md
├── Reference
│   ├── Elements
│   ├── Methods
│   ├── Others ?
│   └── index.md
└── Tutorials
    ├── tutorial_one
    ├── tutorial_two
    └── index.md

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

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

维护计划

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

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

如果在六个月的期限内未观察到积极的变化，并且文档出现以下任一状态：

过时或未维护
停滞不前，未完成
质量低下
过时

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

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

帮助改进 MDN

了解如何贡献

此页面最后修改于 2025年3月19日，由 MDN 贡献者。

在 GitHub 上查看此页面 • 报告此内容的错误

Web 标准技术

非 Web 标准技术