我们撰写的内容
MDN Web Docs 包含 *浏览器中立* 文档,使 Web 开发人员能够编写 *浏览器无关* 代码。在本文中,您将找到有关是否应在 MDN Web Docs 上包含给定主题和/或内容类型的信息。
编辑政策
本节描述了 Mozilla MDN 员工制定的政策,以管理 MDN Web Docs 上的内容。所有 MDN Web Docs 贡献者都应遵守这些政策。
相关性
MDN Web Docs 上的所有内容都必须与它所出现的技术部分相关。垃圾邮件(商业广告)和其他不相关的内容将永远不会被接受到网站上。Mozilla MDN 员工可自行决定禁止持续尝试提交垃圾邮件的贡献者访问 MDN。
指向与链接来源主题相关的商业网站的外部链接将根据具体情况进行判断。它们在帮助 Web 开发人员方面的价值必须超过链接网站的商业利益。
中立性
MDN Web Docs 上的文章必须保持 中立的观点,在不带编辑偏见的情况下报告浏览器差异。不允许对任何浏览器或用户代理发表贬损性评论。
标准化
要在 MDN Web Docs 上记录的 Web 技术应处于标准化轨道上,并且必须至少由一个渲染引擎实现。浏览器支持的差异记录在文章的 浏览器兼容性 部分。
建议内容
属于 MDN Web Docs 的主题
一般来说,如果它是一个开放的 Web 技术,我们就会在 MDN Web Docs 上记录它。这包括 Web 开发人员现在和将来可以用来创建网站和应用程序的任何功能。
如果某个功能由多个浏览器实现,并且已被接受为标准或正在走向标准化,那么是的,我们肯定会在这里记录它。如果某个功能仍处于实验阶段,并且尚未在多个浏览器中实现和/或容易发生变化,那么它仍然适合包含在内,但可能不会被视为编写团队优先处理的工作。
换句话说,要在 MDN Web Docs 上记录的 Web 技术应满足以下所有标准
- 处于标准化轨道上。
- 在可靠的标准机构发布的规范中指定。
- 至少由一个渲染引擎实现。
- 在稳定的浏览器版本中发布。
我们的主要重点是编写以下前端 Web 技术
我们还记录了一些更广泛的主题,例如 SVG、XML、WebAssembly 和 无障碍访问。此外,我们还为这些技术提供了广泛的 学习指南 以及 术语表。
注意:后端技术通常在其他地方有自己的文档,MDN Web Docs 不会试图取代它们,尽管我们 确实有一些例外情况。
MDN Web Docs 上的所有内容都必须与它所出现的技术部分相关。贡献者应遵循这些 MDN 写作指南,以了解写作风格、代码示例和其他主题。
有关是否可以在 MDN Web Docs 上记录技术的标准的更多详细信息,请参阅 包含标准 页面。
当我们记录一项新技术时
在 MDN Web Docs 上,我们不断努力根据需要记录新的 Web 标准技术。我们试图在发布文档的时间上取得平衡,既要足够早,以便开发人员可以在需要时尽快了解新功能,又要足够晚,以便该技术成熟稳定,这样文档就不需要不断更新或快速删除。
一般来说,我们考虑记录新技术的最早时间是:*当该功能处于标准化轨道上并在某个地方实现时*。
如果新技术满足以下条件,我们会考虑记录它
- 在可靠的标准组织(如 W3C、WHATWG、Khronos、IETF 等)下发布的规范文档中指定,并且已达到合理的稳定级别(例如,W3C 工作草案或候选推荐,或者当规范看起来相当稳定时,通过针对它的问题流来判断),并且
- 至少在一个浏览器中一致实现,其他浏览器开发人员也表现出兴趣的迹象(例如,存在活动票证或“实施意图”流程正在生效)。
如果新技术满足以下条件,我们不会记录它
- 没有规范,或者规范只是一个看起来容易发生变化的粗略笔记,
- 一个或零个浏览器目前已实现它,并且不支持的浏览器没有表现出实施它的兴趣。您可以通过询问在这些浏览器上工作的工程师以及查看浏览器错误跟踪器和邮件列表等来判断这一点,
- 不是 Web 公开技术和/或完全专有,或者
- 它已经显示出被弃用或被类似功能取代的迹象。
不属于 MDN Web Docs 的主题
一般来说,任何不是开放 Web 标准的内容都不属于 MDN Web Docs。垃圾邮件(商业广告)和其他不相关的内容将永远不会被接受到网站上。Mozilla MDN 员工可自行决定禁止持续尝试提交垃圾邮件的贡献者访问 MDN。
MDN Web Docs 不合适主题的示例包括
- 未公开给 Web 且特定于浏览器的技术。
- 与 Web 无关的技术。
- 面向最终用户的文档。例如,对于 Mozilla 产品,此类文档应位于 Mozilla 支持网站 上。
- 自链接或自我宣传的外部链接。在添加外部链接之前,请查看我们 写作风格指南 中的这些指南。
当我们删除文档时
如果页面不再包含任何有用的信息、已过时或可能不准确到使保留它们具有误导性,则会从 MDN Web Docs 中删除。
以下示例描述了可能删除页面/内容的情况
- 文章包含有关未在所有浏览器中实现且后来被撤回的功能的信息(通常是实验性功能,例如带前缀的功能)。
- 参考页面描述在任何浏览器中实现之前已从规范中删除的功能。
- 文章涵盖后来被证明是不良实践并被更好的技术取代的技术。
- 文章包含后来被其他更优质文章取代的信息。
- 文章包含不适合 MDN Web Docs 的内容。
- MDN Web Docs 的部分内容不侧重于开放 Web 技术,并且是维护负担。
有关 *如何* 删除文档的更多信息,请参阅 创建、移动和删除页面 指南。
MDN Web Docs 允许的文档类型
通常,我们的文档分为以下几类
- 参考
- 指南
- 术语表
- 学习/教程
一般来说,MDN Web Docs 用于产品文档,而不是项目或流程文档。因此,如果文档是关于“如何使用某物”或“某物如何工作”(其中,“某物”属于上述主题类别之一),则可以将其放在 MDN Web Docs 上。
如果文档是关于“谁正在开发某物”或“开发某物的计划”,则不应将其放在 MDN Web Docs 上。
以下是一些不应放在 MDN Web Docs 上的文档类型示例
- 计划文档
- 设计文档
- 项目建议书
- 规范或标准
- 宣传材料、广告或个人信息