写作风格指南

目标是编写包含读者可能需要的所有信息的页面，以了解手头的主题。

以下小节提供了实现此目标的建议

• 考虑您的目标受众
• 考虑写作的三个 C
• 包含相关的示例
• 提供描述性引言
• 使用包容性语言
• 以 SEO 为导向进行写作

牢记您正在撰写内容的目标受众。例如，关于高级网络技术的页面可能不需要像关于网络的典型页面那样详细介绍基础网络概念。请记住，这些只是指南。在某些情况下，这些技巧可能并不适用。

优秀写作的三个 C 是清晰、简洁和一致。

• 清晰：确保您的写作清晰明了。一般来说，使用主动语态和明确的代词。写短句子，每个句子只表达一个意思。在使用新术语之前，请为其定义，并考虑目标受众。
• 简洁：在撰写任何文档时，了解要表达多少内容非常重要。如果提供过多的细节，页面会变得乏味且难以阅读，很少会被使用。
• 一致：确保在整个页面和多个页面中始终使用相同的措辞。

一般来说，添加示例或真实场景可以更好地解释您正在撰写的内容。这有助于读者以更切实和实用的方式理解概念和程序信息。

您应该使用示例来阐明每个参数的用途，并阐明可能存在的任何边缘情况。您还可以使用示例来演示常见任务的解决方案以及可能出现的问题的解决方案。

确保第一个标题之前的开头段落充分概括了页面将涵盖的信息，以及读者在阅读完内容后可能能够实现的目标。这样，读者可以快速确定页面是否与他们的关注点和期望的学习成果相关。

在指南或教程中，引言段落应告知读者将要涵盖的主题，以及读者期望具备的先决知识（如果有）。引言段落应提及正在记录或讨论的技术和/或 API，并提供相关信息的链接，并提供提示，说明文章内容可能在哪些情况下有用。

• 简短引言示例：此引言示例过于简短。它省略了太多信息，例如“描边”文本的确切含义、文本绘制的位置等等。

  CanvasRenderingContext2D.strokeText() 绘制字符串。

• 冗长引言示例：此示例更新了引言，但现在过于冗长。包含了过多的细节，并且文本深入描述了其他方法和属性。相反，引言应重点关注 strokeText() 方法，并参考描述其他细节的相关指南。

  调用 Canvas 2D API 方法 CanvasRenderingContext2D.strokeText() 时，它会描边指定字符串中的字符，从指定的坐标开始，使用当前笔颜色。在计算机图形学术语中，“描边”文本意味着绘制字符串中字形的轮廓，而不用颜色填充每个字符的内容。

  文本使用上下文的当前字体绘制，如上下文中的 font 属性指定。

  文本相对于指定坐标的位置由上下文的 textAlign、textBaseline 和 direction 属性决定。textAlign 控制字符串相对于指定的 X 坐标的位置；如果值为 "center"，则字符串从 x - (stringWidth / 2) 开始绘制，将指定的 X 坐标放置在字符串的中间。如果值为 "left"，则字符串从指定的 x 值开始绘制。如果 textAlign 为 "right"，则文本绘制使其结束于指定的 X 坐标。

  (…)

  您可以选择提供第四个参数，以像素为单位指定字符串的最大宽度。如果您提供此参数，则在绘制时，文本会水平压缩或缩放（或以其他方式调整）以适合该宽度空间。

  您可以调用 fillText() 方法以用颜色填充绘制字符串的字符，而不是仅绘制字符的轮廓。

• 合适的引言示例：在这里，我们看到了 strokeText() 方法的更好的概述。

  CanvasRenderingContext2D 方法 strokeText() 是 Canvas 2D API 的一部分，它描边（绘制轮廓）指定字符串的字符，并以给定的 X 和 Y 坐标指示的位置为锚点。文本使用上下文的当前 font 绘制，并根据 textAlign、textBaseline 和 direction 属性进行对齐和调整。

  有关更多详细信息和示例，请参阅“绘制图形”页面上的 文本 部分，以及我们关于该主题的主要文章 绘制文本。

MDN 拥有广泛而多元的受众。我们强烈建议尽可能保持文本的包容性。以下是一些文档中常用术语的替代方案

• 避免使用 主控 和 从属 这些术语，而应使用 主 和 副本。
• 将 白名单 和 黑名单 替换为 允许列表 和 拒绝列表。
• 健全性 应替换为 一致性。
• 不要使用 虚拟，而应使用 占位符。
• 在文档中不需要使用 疯狂 和 精神错乱 这些术语；但是，如果出现这种情况，请考虑使用 奇妙 代替。

在任何性别与主题无关的写作中，最好使用中性语言。例如，如果您正在谈论某个特定男性的行为，使用“他/他的”是可以的；但如果主题是男性或女性，则“他/他的”不合适。

让我们看看以下示例

• 错误：“确认对话框询问用户是否允许网页使用他的网络摄像头。”
• 错误：“确认对话框询问用户是否允许网页使用她的网络摄像头。”

这两个版本都使用了性别特定的代词。要解决此问题，请使用中性代词，如下所示

• 正确：“确认对话框询问用户是否允许网页使用他们的网络摄像头。”

另一种选择是将用户变为复数，如下所示

• 正确：“确认对话框询问用户是否允许网页使用他们的网络摄像头。”

当然，最好的解决方案是改写并删除代词

• 正确：“出现一个确认对话框，请求用户授权访问网络摄像头。”
• 正确：“出现一个确认对话框，询问用户是否允许使用网络摄像头。”

这种处理问题的最后一种方法可以说是最好的。它不仅语法上更正确，而且消除了处理不同语言中可能具有截然不同的性别规则的性别问题所带来的复杂性。此解决方案可以使读者和翻译人员更容易进行翻译。

虽然 MDN Web Docs 上任何写作的主要目标始终是解释和告知开放网络技术，以便开发人员可以快速学习如何做他们想做的事情，或者找到他们需要知道的细枝末节以完善他们的代码，但重要的是他们能够找到我们编写的材料。我们可以通过在写作时牢记搜索引擎优化（SEO）来实现这一点。

本节涵盖了内容的标准实践、建议和要求，以帮助确保搜索引擎能够轻松地对我们的材料进行分类和索引，从而确保读者能够轻松找到他们需要的内容。SEO 指南包括确保编写者和编辑处理的每个页面都经过合理的设计、编写和标记，以便为搜索引擎提供它们需要正确索引文章的上下文和线索。

在编写和审查内容时，请牢记以下清单，以帮助确保页面及其相邻页面能够被搜索引擎正确索引

• 确保页面内容不过于相似：如果不同页面上的内容在文本上相似，搜索引擎将假设这些页面是关于同一件事的，即使它们并非如此。例如，如果一个接口具有width和height属性，那么这两个属性的文档页面上的文本很容易出奇地相似，只需交换几个词并使用相同的示例即可。这使得搜索引擎难以区分哪个是哪个，并且它们最终共享页面排名，导致两者都比应该的更难找到。因此，务必确保每个页面都有其自己的内容。以下是一些帮助您实现此目标的建议
  • 解释更多独特的概念：考虑可能存在比人们想象中更多差异的用例。例如，在记录width和height属性的情况下，也许可以编写有关水平空间和垂直空间如何以不同方式使用，并提供关于适当概念的讨论。也许您可以根据为侧边栏腾出空间来提及width的使用，同时使用height来处理垂直滚动或页脚。包含有关可访问性问题的信息也是一个有用且重要的想法。
  • 使用不同的示例：在这种情况下，示例通常甚至比正文文本更相似，因为示例可能从一开始就同时（或全部）使用了类似的方法或属性，因此在重复使用时无需进行任何真正的更改。因此，丢弃该示例并编写一个新的示例，或者至少提供多个示例，其中至少有一些是不同的。
  • 为示例添加描述：应包含对示例作用的概述以及如何工作的说明，其详细程度应与主题的复杂性和目标受众相符。
  避免过度相似最简单的方法当然是如果时间允许的话从头开始编写每一篇文章。
• 确保页面内容不短于300字：如果页面上的内容过少（在 SEO 行话中称为“薄页面”），搜索引擎将无法准确（或根本无法）编目此类页面。内容过短的页面很难找到。作为指导原则，确保 MDN Web Docs 上的页面长度不短于大约 300 字左右。不要人为地夸大页面内容，但尽可能将此指南视为最小目标长度。以下是一些基本指南，可帮助您创建内容量足以进行正确搜索的页面，而无需在页面中添加不必要的文本
  • 避免存根页面：显然，如果文章是存根或缺少内容，请添加它。我们尽量避免在 MDN Web Docs 上出现完全的“存根”页面，尽管它们确实存在，但仍有许多页面缺少大部分内容。
  • 审查页面结构：审查页面以确保其结构与其页面类型相符。检查以确保所有部分都存在并具有相应的内容。
  • 确保完整性：审查各部分以确保没有信息丢失。确保列出并解释所有参数。确保涵盖任何异常情况——这是内容缺失的特别常见的地方。
  • 确保所有概念都得到充分阐述：很容易对某件事进行快速解释，但请确保涵盖所有细微差别。是否有特殊情况？读者可能需要了解哪些已知的限制？
  • 添加示例：应该有示例涵盖所有参数，或者至少涵盖从初学者到中级用户可能使用的参数（或属性、或特性），以及需要额外解释的任何高级参数。每个示例之前都应概述该示例的作用，以及可能需要哪些其他知识才能理解它，等等。在示例之后（或散布在示例的各个部分之间）应有文本解释代码的工作原理。不要吝惜细节或示例中错误的处理。请记住，用户会复制粘贴您的示例以将其用于他们自己的项目，并且您的代码会最终用于生产网站！请参阅我们的代码示例指南以获取更多有用的信息。
  • 解释用例：如果所描述的功能存在特别常见的用例，请谈论它们！不要假设用户会弄清楚正在记录的方法可以用来解决常见的开发问题，而应实际添加一个关于该用例的部分，其中包含一个示例和解释示例工作原理的文本。
  • 添加图像信息：在所有图像和图表上包含正确的alt文本。此文本以及表格和其他图形上的标题都算在内，因为蜘蛛无法抓取图像，因此alt文本告诉搜索引擎爬虫嵌入的媒体包含什么内容。

    注意：不建议为了操纵搜索引擎排名而包含过多与功能无关的关键词或关键词；这种行为很容易被发现，并且往往会被处罚。同样，不要为了提高页面的大小和搜索排名，在页面本身中添加重复的、无用的材料或关键词块。这弊大于利，既会影响内容的可读性，也会影响我们的搜索结果。

• 专注于主题内容：围绕页面的主题而不是特定的关键词编写内容要好得多。对于给定的主题，您很可能可以包含许多关键词；事实上，许多 SEO 会根据文章的长度，汇编一个包含 5 到 100 个不同关键词（短、中和长尾关键词）的列表，以包含在他们的文章中。这样做会使您的措辞多样化，从而减少重复。

除了用英语编写语法正确的句子外，我们建议您遵循以下指南，以确保 MDN Web Docs 上的内容保持一致。

• 缩写和首字母缩写词
• 大写
• 缩写
• 数字和数字
• 复数
• 撇号和引号
• 逗号
• 连字符
• 拼写
• 术语
• 语态

缩写是较长单词的简写版本，而首字母缩写词是使用短语中每个单词的第一个字母创建的新词。本节描述了缩写和首字母缩写词的指南。

• 扩展：在页面上第一次提到某个术语时，扩展用户可能不熟悉的首字母缩写词。如有疑问，请扩展该术语。更好的是，将其链接到描述该技术的文章或词汇表条目。
  • 正确：“XUL（XML 用户界面语言）是 Mozilla 基于 XML 的语言……”
  • 错误：“XUL 是 Mozilla 基于 XML 的语言……”
• 大写和句点：在所有缩写和首字母缩写词中使用全大写并删除句点，包括“US”和“UN”等组织。
  • 正确：XUL
  • 错误：X.U.L.；Xul
• 拉丁文缩写：您可以在括号表达式和注释中使用常见的拉丁文缩写（例如，即，例如）。在这些缩写中使用句点，后跟逗号或其他适当的标点符号。
  • 正确：Web 浏览器（例如，Firefox）可以用来……
  • 错误：Web 浏览器例如 Firefox 可以用来……
  • 错误：Web 浏览器，例如 Firefox，可以用来……
  • 错误：Web 浏览器，（例如：Firefox）可以用来……
  在普通文本（即注释或括号外的文本）中，使用缩写的英文等价词。
  • 正确：……网络浏览器，等等。
  • 错误：……网络浏览器，等等。
  • 正确：可以使用 Firefox 等 Web 浏览器……
  • 错误：Web 浏览器例如 Firefox 可以用来……
  下表总结了拉丁文缩写的含义和英文等价词

  缩写	拉丁文	英文
  cf.	confer	比较
  e.g.	exempli gratia	例如
  et al.	et alii	以及其他
  etc.	et cetera	等等
  i.e.	id est	也就是说，换句话说
  N.B.	nota bene	注意
  P.S.	post scriptum	附言

  注意：始终考虑使用拉丁文缩写是否真正有益。其中一些很少使用，以至于许多读者要么会混淆，要么无法理解其含义。

  此外，如果您选择这样做，请确保您正确地使用它们。例如，注意不要将“e.g.”与“i.e.”混淆，这是一个常见的错误。

• 缩写和首字母缩写词的复数：对于缩写和首字母缩写词的复数，添加s。永远不要使用撇号。请。
  • 正确：CD-ROMs
  • 错误：CD-ROM's
• “Versus”、“vs.”和“v.”：如果使用缩写，“vs.”优于“v.”，并且可以在标题中使用。文本中的其他地方，使用拼写形式“versus”。
  • 正确：这个 vs. 那个
  • 错误：这个 v. 那个

  • 正确：this versus that

正文中使用标准英语的 capitalization 规则，并将“World Wide Web”首字母大写。可以使用小写字母表示“web”（单独使用或用作修饰语）和“internet”。

键盘按键应使用句子式大小写，而不是全部大写。例如，“Enter”而不是“ENTER”。唯一的例外是您可以使用“ESC”来缩写“Escape”键。

某些单词应始终大写，例如包含大写字母的商标或源自人名的单词（除非该单词用在代码中，并且代码语法需要小写）。一些示例包括

• Boolean（以英国数学家和逻辑学家George Boole命名）
• JavaScript（Oracle Corporation 的商标，应始终按商标形式编写）
• Python、TypeScript、Django 和其他编程语言和框架名称

我们的写作风格倾向于随意，因此如果您愿意，可以随意使用缩写词（例如，“don't”、“can't”、“shouldn't”）。

• 逗号：在连续文本中，仅在五位数及以上的数字中使用逗号。
  • 正确: 4000; 54,000
  • 错误: 4,000; 54000
• 日期：对于日期（不包括代码示例中的日期），请使用“1900年1月1日”的格式。
  • 正确：1906年2月24日
  • 错误：1906年2月24日；1906年2月24日；24/02/1906
  或者，您可以使用 YYYY/MM/DD 格式。
  • 正确: 1906/02/24
  • 错误: 02/24/1906; 24/02/1906; 02/24/06
• 年代：使用“1990s”的格式。不要使用撇号。
  • 正确：1920s
  • 错误：1920's
• 数字的复数：添加“s”。不要使用撇号。
  • 正确：486s
  • 错误：486's

使用英语风格的复数，而不是拉丁语或希腊语影响的形式。

• 正确：syllabuses, octopuses
• 错误：syllabi, octopi

不要使用“弯曲”的引号和双引号。在 MDN Web Docs 上，我们只使用直引号和撇号。这是因为我们需要为一致性选择其中一个。如果弯曲的引号或撇号出现在代码片段中，即使是内联代码片段，读者也可能会复制粘贴它们，期望它们能够发挥作用（但实际上它们不会）。

• 正确：请不要使用“弯曲的引号”。
• 错误：请不要使用“弯曲的引号”。

以下列表描述了一些我们需要了解逗号用法规则的常见情况

• 在引导从句之后：引导从句是从属从句，通常位于句子的开头。在引导从句之后使用逗号将其与后面的独立从句分开。
  • 示例 1
    • 正确：“在这个示例中，您将看到如何使用逗号。”
    • 错误：“在这个示例中您将看到如何使用逗号。”
  • 示例 2
    • 正确：“如果您正在寻找指南，那么您来对地方了。”
    • 错误：“如果您正在寻找指南您来对地方了。”
  • 示例 3
    • 正确：“在移动平台上，您倾向于获得一个数字键盘来输入数据。”
    • 错误：“在移动平台上您倾向于获得一个数字键盘来输入数据。”
• 在连词之前：串行逗号（也称为“牛津逗号”）是在三个或更多项目序列中连词之前的逗号。在 MDN Web Docs 上，我们使用串行逗号。逗号也用于分隔列表中的每个项目。
  • 正确：“我将乘坐火车、飞机和汽车旅行。”
  • 错误：“我将乘坐火车、飞机和汽车旅行。”
  在包含两个项目的列表中，不要在“and”和“or”之前使用逗号。
  • 正确：“我的狗很可爱也很聪明。”
  • 错误：“我的狗很可爱，也很聪明。”
  如果连词“and”、“but”和“or”连接两个独立从句，则在它们之前使用逗号。但是，如果句子由于连词而变得非常长或复杂，请考虑将其重写为两个句子。
  • 示例 1
    • 正确：“您可以执行此步骤，但您需要注意文件设置。”
    • 错误：“您可以执行此步骤但您需要注意文件设置。”
  • 示例 2
    • 正确：“我的父亲很严格但很慈爱。”
    • 错误：“我的父亲很严格，但很慈爱。”
• 在“that”和“which”之前：限制性从句对于句子的含义至关重要，不需要逗号将其与句子的其余部分隔开。限制性从句通常由“that”引导，并且不应该在其前面使用逗号。
  • 正确：“我们已经整理了一个课程，其中包含您为实现目标所需的所有基本信息。”
  • 错误：“我们已经整理了一个课程，其中包含您为实现目标所需的所有基本信息。”
  非限制性从句提供附加信息，对于句子的含义来说不是必需的。非限制性从句通常由“which”引导，并且其前面应使用逗号。
  • 正确：“您编写一个策略，该策略是每个功能的允许来源列表。”
  • 错误：“您编写一个策略，该策略是每个功能的允许来源列表。”
• 在“such as”之前：如果“such as”是非限制性从句的一部分，并且句子的其余部分是独立从句，则在“such as”之前使用逗号。
  • 正确：“Array 对象具有用于以各种方式操作数组的方法，例如连接、反转和排序它们。”
  • 错误：“Array 对象具有用于以各种方式操作数组的方法，例如连接、反转和排序它们。”
  下面的示例显示了何时不应在“such as”处使用逗号。此处包含“such as”的从句对于句子的含义至关重要。
  • 正确：“Web 应用程序通过添加诸如音频和视频处理以及允许使用 WebSockets 访问原始数据等功能变得更加强大。”
  • 错误：“Web 应用程序通过添加功能变得更加强大，例如音频和视频处理，以及允许使用 WebSockets 访问原始数据。”

复合词仅在前缀的最后一个字母是元音并且与词根的第一个字母相同的情况下才使用连字符。

• 正确：re-elect, co-op, email
• 错误：reelect, coop, e-mail

使用美式英语拼写。

一般来说，使用Dictionary.com上的第一个条目，除非该条目被列为变体拼写或主要用于非美式英语形式。例如，如果您查找“behaviour”（在美式标准形式中添加了额外的u），您会发现短语“Chiefly British”后面跟着指向美式标准形式的链接，“behavior”。不要使用变体拼写。

• 正确：localize, behavior, color
• 错误：localise, behaviour, colour

这些是我们使用某些技术术语的建议

• HTML 元素：使用“element”一词来指代 HTML 和 XML 元素，而不是“tag”。此外，元素应包含在尖括号“<>”中，并应使用反引号（`）进行样式设置。例如，在反引号内使用 <input> 将使其样式设置为 <input>，这符合预期。
  • 正确：<span> 元素
  • 错误：span 标签
  在 MDN 上，您可以选择在HTMLElement 宏中指定 HTML 元素，这将设置元素的样式，添加尖括号“<>”以及添加指向其参考页面的链接。
  • 使用反引号：<span>
  • 使用宏：<span>（markdown 中的源代码：{{HTMLElement("span")}})
• 参数与实参：MDN Web Docs 上的首选术语是参数。请尽可能避免使用“实参”一词以保持一致性。
• 用户界面操作：在任务序列中，使用祈使语气描述用户界面操作。通过其标签和类型识别用户界面元素。
  • 正确：“单击“编辑”按钮。”
  • 错误：“单击“编辑”。

虽然主动语态是首选，但考虑到我们内容的非正式风格，被动语态也是可以接受的。不过，请尽量保持一致。

本节列出了每个页面不同部分（如标题、注释、链接和示例）应遵循的指南。

• 代码示例
• 交叉引用（链接）
• 外部链接
• 缩短的 URL（短链接）
• 标题级别
• 图像和其他媒体
• 列表
• 另请参阅部分
• 子页面
• 标识符
• 标题

MDN Web Docs 上的一个页面可以包含多个代码示例。以下列表介绍了在为 MDN Web Docs 编写代码示例时的一些推荐做法

• 每个示例代码片段应包含
  • 标题：一个简短的 ###（<h3>）标题来描述通过代码示例演示的场景。例如，“使用胶印”和“恢复到上一层的样式”。
  • 描述：在示例代码之前的一个简短描述，说明您希望引起读者注意的示例的具体内容。例如，“在下面的示例中，在 CSS 中定义了两个级联层，base 和 special。”
  • 结果说明：示例代码之后的一个说明，描述结果以及代码的工作原理。
• 通常，代码示例不仅应该演示功能的语法以及如何使用它，还应该突出显示 Web 开发人员可能希望或需要使用该功能的目的和情况。
• 如果您正在处理一段较大的示例代码，将其分解成较小的逻辑部分可能是有意义的，以便可以单独对其进行描述。
• 在添加实时示例时，需要注意的是，所有具有相同类型（HTML、CSS 和 JavaScript）的示例代码块在运行示例之前会连接在一起。这使您可以将代码分解成多个片段，每个片段可以选择性地包含自己的描述、标题等。这使得代码文档编写变得非常强大和灵活。

要了解如何为 MDN Web Docs 设置代码示例的样式或格式，请参阅代码样式指南。

当在 MDN 上引用其他页面或页面部分的标题时，请在链接文本中遵循句子大小写（与页面或部分标题匹配）。即使链接文本的大小写与链接的页面标题或部分标题不同，也请使用句子大小写（页面或部分标题中使用的大小写可能不正确）。不要在链接文本周围使用引号。要按标题引用 MDN 上的页面，请使用以下样式

• 正确：“请参阅Ordering flex items指南。”
• 错误：“请参阅“Ordering flex items”指南。”

链接到页面上的某个部分时，请遵循类似的样式，如下所示

• 正确：“有关更多信息，请参阅内存管理页面上的Allocation in JavaScript部分。”

如果要链接的部分在同一页面上，可以使用“上面”或“下面”来提示该部分的位置。

• 正确：“此概念在下面Accessibility部分中进行了更详细的描述。”

您可以将句子的部分链接到文章或文章的部分。请注意使用描述性短语作为链接文本，以便为链接的页面提供足够的上下文。

• 正确：“了解更多关于如何排列弹性项目的信息。”
• 错误：“点击这里了解更多信息。”
• 错误：“阅读这篇文章以了解更多信息。”

在 MDN 上，链接到参考页面的另一种方法是使用宏。这些宏在Commonly-used macros页面上进行了描述。例如，要链接到 HTML 元素的参考页面，请使用HTMLElement宏；要链接到 CSS 属性的参考页面，请使用CSSxRef宏。

我们在参考页面、术语表页面和指南结尾处的See also部分中遵循类似的交叉引用指南。

在特定情况下，MDN Web Docs 允许使用外部链接。使用本节中描述的指南来确定是否可以在 MDN Web Docs 上包含外部链接。如果您添加的外部链接不符合此处描述的指南，您的拉取请求将被拒绝。

一般来说，如果您正在考虑添加外部链接，则需要确保以下风险降到最低

• 链接失效或过时
• 出现背书，尤其是商业产品或服务
• 试图利用 MDN Web Docs 分发垃圾邮件
• 模糊链接目标的短链接

• 好的外部链接：好的外部链接将读者引导至相关、持久且广受信任的资源。您应该优先添加指向以下外部内容的链接：
  • 唯一或不可或缺的（例如，IETF RFC）
  • 必要的归属、引用或确认（例如，作为 Creative Commons 归属的一部分）
  • 比在 MDN Web Docs 本身合并此类内容更有可能维护主题（例如，供应商的发布说明）
  • 开源或社区驱动的，如 MDN Web Docs 本身
• 不好的外部链接：不好的外部链接缺乏相关性、可维护性、可访问性，或者以其他方式对读者设置障碍。避免添加指向以下外部内容的链接：
  • 通用或非特定的（例如，供应商的主页，而不是相关的文档）
  • 短暂或未维护的（例如，一次性公告）
  • 自我链接或自我推销（例如，作者在 MDN Web Docs 之外的作品）
  • 付费墙（例如，爱好者、学生或生活在低收入国家的读者无法承受的昂贵课程）
  • 无法访问（例如，没有字幕的视频）
• 自我推销或垃圾邮件链接：虽然个人博客文章、会议演讲或 GitHub 存储库具有价值，但链接到您自己的资源可能会造成利益冲突的印象。在链接到您与之存在业务或个人关系的资源之前，请三思而后行。

  注意：如果您与链接的目标存在业务或个人关系，则必须在您的拉取请求中披露该关系。未能这样做可能会危及您继续参与 MDN Web Docs 的资格。

  有时这些链接是相关且合适的。例如，如果您是规范的编辑，并且正在为与该规范相关的文档做出贡献，那么链接到该规范是预期和可接受的。但您必须披露您与链接之间的关系。

URL 缩短器（如 TinyURL 或 Bitly）非常适合将长链接缩短为简短易记的 URL（也称为“短链接”）。但是，它们也会模糊 URL 的目标。此外，对于某些缩短器，目标可以在创建后更改，此功能可用于恶意目的。

不要使用通过第三方（用户生成）URL 缩短器创建的链接。例如，如果https://myshort.link/foobar是由随机用户生成的短 URL，并重定向到https://example.com/somelongURL/details/show?page_id=foobar，请使用较长的example.com URL。

另一方面，鼓励使用由也维护目标 URL 的组织维护的第一方缩短器。https://bugzil.la由 Mozilla 拥有和运营，是一个 URL 缩短器，它重定向到https://bugzilla.mozilla.org/，这也是 Mozilla 拥有的域名。在这种情况下，请使用较短的 URL。例如，使用https://bugzil.la/1682349而不是https://bugzilla.mozilla.org/show_bug.cgi?id=1682349。

当新段落开始新部分时，应添加标题。按降序使用这些 Markdown 标题级别，不要跳过级别：##、###和####；它们分别转换为HTML 标题标签<h2>、<h3>和<h4>标签。

##是允许的最高级别，因为#保留用于页面标题。我们建议不要添加超过三个级别的标题。如果您觉得需要添加第四个标题级别，请考虑将文章分解成几个较小的文章，并创建一个登录页面。或者，看看是否可以使用项目符号来呈现信息，以避免添加第四级标题。

在为小节创建标题时，请记住以下注意事项

• 不要创建单个小节。不要将主题细分为单个子主题。要么有两个或更多子标题，要么根本没有。
• 不要在标题中使用内联样式、类或宏。但是，您可以使用反引号来指示代码术语（例如，“使用FooBar接口”）。
• 不要创建“碰撞标题”。这些标题紧跟在一个子标题后面，中间没有内容文本。这看起来不好，并且让读者在外部部分的开头没有任何解释性文本。

如果您在页面上包含图像或其他媒体，请遵循以下指南

• 确保媒体许可证允许您使用它们。尝试使用具有非常宽松许可证的媒体，例如CC0，或者至少与我们的通用内容许可证兼容的许可证——Creative Commons Attribution-ShareAlike license（CC-BY-SA）。
• 对于图像，请通过https://tinypng.com或https://imageoptim.com运行它们以减轻页面重量。
• 对于SVG，请通过SVGOMG运行代码，并确保SVG文件在文件末尾有一行空行。
• 每个图像都必须包含描述性的alt文本。

列表应在所有页面上以一致的方式格式化和结构化。各个列表项应使用合适的标点符号编写，无论列表格式如何。但是，根据您正在创建的列表类型，您需要调整您的写作，如下面的部分所述。在这两种情况下，都包含一个引导句，描述列表中的信息。

• 项目符号列表：项目符号列表用于对相关的简要信息进行分组。列表中的每个项目都应遵循类似的句子结构。项目符号列表中的句子和短语（即缺少动词或主语或两者兼而有之的句子片段）应包含标准标点符号——句子以句号结尾，短语则不以句号结尾。如果列表项中有多个句子，则每个句子的末尾都必须出现句号，包括列表项的最后一个句子，就像段落中预期的那样。这是一个结构正确的项目符号列表的示例

  在此示例中，我们应包含

  • 一个条件，并附有简要说明。
  • 一个类似的条件，并附有简要说明。
  • 另一个条件，并附有更详细的说明。

  注意，相同的句子结构是如何从一个项目符号重复到另一个项目符号的。在此示例中，每个项目符号都陈述一个条件，后跟逗号和简要说明，并且列表中的每个项目都以句号结尾。如果列表项包含不完整的句子，则末尾不需要句号。例如

  以下与颜色相关的属性在此场景中将很有帮助

  • propertyA：设置背景颜色
  • propertyB：为文本添加阴影

  如果一个或多个列表项是完整的句子，则在每个列表项后使用句号，即使列表项包含三个或更少的单词也是如此。但是，尽可能遵循列表中所有项目的相同结构；确保所有列表项要么是完整的句子，要么是短语。
• 编号列表：编号列表主要用于枚举一组指令中的步骤。由于指令可能很复杂，因此清晰度是重中之重，尤其是在每个列表项中的文本很长的情况下。与项目符号列表一样，请遵循标准标点符号用法。这是一个结构正确的编号列表的示例

  为了正确构建编号列表，您应该

  1. 以标题或简短的段落开头，介绍说明。在开始说明之前，为用户提供上下文非常重要。
  2. 开始创建说明，并将每个步骤放在其自己的编号项中。您的说明可能非常广泛，因此务必写得清楚并使用正确的标点符号。
  3. 完成说明后，请在编号列表后面加上简短的总结或说明，说明完成后预期结果。

  以下是为上述列表编写结束说明的示例

  我们创建了一个简短的编号列表，其中提供了生成格式正确的编号列表的说明步骤。

  请注意，编号列表中的项目如何像简短的段落一样阅读。由于编号列表通常用于说明目的或引导某人完成有序的过程，因此请确保每个项目都保持重点：每个步骤一个编号项。

MDN Web Docs 上的大多数指南、参考页面，甚至术语表页面，在文章末尾都包含一个See also部分。此部分包含与 MDN 中的相关主题的交叉引用，有时还包含指向相关外部文章的链接。例如，这是@layer页面的See also 部分。

一般来说，请以项目符号列表格式在 See also 部分中呈现链接，列表中的每个项目都作为一个短语。但是，在 MDN 上的Learn web development区域中，See also 部分遵循定义列表格式。

为了保持 MDN Web Docs 的一致性，在添加或更新 See also 部分时，请牢记以下指南。

链接文本

• 链接文本应与链接到的页面或部分的标题相同。例如，指向此 ARIA 页面的链接文本，其页面标题为“ARIA 状态和属性”，将为
  • 正确：ARIA 状态和属性
• 即使链接文本与链接的页面标题或部分标题不同，也请使用句子大小写。页面或部分标题中使用的案例可能不正确。例如，指向 Quirks Mode 页面的链接文本，正确的句子大小写将为
  • 正确：Quirks 模式
• 对于外部链接，即使目标文章页面上的大小写不同，也请使用句子大小写。这样做是为了确保 MDN Web Docs 的一致性。例外情况包括书籍名称。
• 在 MDN 上，您可以选择使用宏来链接到页面，如 引用中链接到页面 部分（在“常用宏”页面上）中所述。使用宏将在链接文本中的关键字中添加代码格式，如以下示例所示。
• 链接列表项开头不需要冠词（“A”，“An”，“The”）。列表项末尾不需要标点符号，因为它始终是一个术语或短语。
  • 正确：revert-layer
  • 错误：The revert-layer keyword.
  • 正确：HTML DOM API
  • 错误：The HTML DOM API
• 如以上示例所示，即使页面和部分标题中未使用格式，也要使用反引号 (`) 为链接文本中的关键字和文字添加代码格式。例如，对于页面标题“Array() 构造函数”，链接文本将为 Array() 构造函数。

描述性文本

• 使链接周围的描述性文本保持最少。如果需要描述，请将其添加到链接文本和冒号之后。将描述措辞为一个短语，没有结尾标点符号。将所有链接文本放在开头，以帮助扫描链接列表。
  • 正确：:checked，:indeterminate：用于样式化复选框的 CSS 选择器
• 在系列中的最后一项之前不要使用连词“and”。
  • 正确：background-color，border-color，color，caret-color，column-rule-color，outline-color，text-decoration-color，text-emphasis-color，text-shadow：其他与颜色相关的属性
• 对于外部链接，只要可行且合适，请尽量指定源网站和出版或上次更新年份（括号内）。提前提供此信息可以让读者清楚地了解点击链接后将到达的目标。出版或上次更新日期可以帮助读者评估链接文章的相关性，还有助于 MDN 维护人员审查长时间未更新的文章的链接。例如，如果您提供指向维基百科上文章的链接，则可以忽略发布/更新日期。以下列表项是在“另请参阅”部分中添加指向 Top-level await 外部文章的链接以及源和年份信息的示例
  • 正确：Top-level await on v8.dev (2019)
• 对于指向书籍的外部链接，您还可以提供作者姓名。您可以在下面的 进一步阅读 部分中看到一些示例。请勿为可能链接到的博客文章或 GitHub 存储库添加作者姓名。

链接顺序

• 首先列出指向 MDN 页面的链接，然后列出指向相关指南和教程页面的链接。此建议顺序主要是为了帮助扫描列表中的项目。
• 如果列表是内部和外部链接的混合，则首先列出内部链接，然后列出外部链接。
• 在每个内部和外部链接组内，按照字母顺序或简单到高级的顺序，无论哪种对上下文更有意义。

当您需要添加一些关于某个主题或主题领域的文章时，通常会通过创建登录页面，然后为每篇单独的文章添加子页面来实现。登录页面应以一段或两段描述主题或技术开头，然后提供子页面的列表以及每个页面的描述。您可以使用我们创建的一些宏自动将页面插入列表中。

例如，考虑 JavaScript 指南，其结构如下

• JavaScript/Guide – 主目录页面
• JavaScript/Guide/JavaScript 概述
• JavaScript/Guide/函数
• JavaScript/Guide/对象模型的详细信息

尽量避免将您的文章放在层次结构的顶部，这会降低网站速度并降低搜索和网站导航的效率。

页面标题显示在页面顶部，可能与页面“slug”（页面 URL 中 <locale>/docs/ 后面的部分）不同。在定义 slug 时，请牢记以下准则

• slug 应保持简短。在创建新的层次结构级别时，slug 中的新级别的组件应只是一个或两个单词。
• slug 应使用下划线作为多字组件，例如 /en-US/docs/Learn/HTML/Introduction_to_HTML/Getting_started 中的 Getting_started。
• 对于每个组件，在 slug 中也请遵循句子大小写，例如前面示例中的 Getting_started。

页面标题用于搜索结果，也用于在页面顶部的面包屑列表中构建页面层次结构。页面标题可能与页面“slug”不同，如 slug 部分所述。

在编写标题时，请牢记以下准则

• 大写样式：在 MDN Web Docs 中，页面标题和章节标题应使用句子样式的大写（仅将第一个单词和专有名词大写），而不是标题样式的大写
  • 正确：“一种创建 JavaScript 滚动的全新方法”
  • 错误：“一种创建 JavaScript 滚动的全新方法”
  我们有许多较旧的页面是在建立此样式规则之前编写的。如果您愿意，可以根据需要随意更新它们。我们正在逐步进行。
• 一般准则：确定要记录的内容以及如何构建该内容是写作的第一步之一。编写目录可以帮助您确定要如何排序信息。首先介绍简单的概念，然后转向更复杂和高级的概念。首先介绍概念性信息，然后转向面向行动的主题。在为页面和部分或子部分编写标题时，请牢记以下准则
  • 从高到低：如 标题级别 部分所述，从较高的 ## 到较低的 ####，不要跳过级别。对于更广泛的介绍性标题，使用较高级别的标题，并在转向较低级别的标题时使用更具体的标题。
  • 逻辑分组：确保所有相关的子部分在逻辑上都分组在较高级别的标题下。命名各个部分的标题可以帮助您进行此练习。
  • 保持标题简短：较短的标题在文本和目录中更容易扫描。
  • 保持标题具体：使用标题传达将在该部分中介绍的具体信息。例如，对于介绍 HTML 元素的部分，使用标题“HTML 元素”，而不是“简介”或“概述”。
  • 保持标题重点突出：使用标题传达一个目标——将在该部分中介绍的单个想法或概念。为此，请尽可能避免在标题中使用连词“and”。
  • 使用并行结构：对同一标题级别的标题使用类似的语言。例如，如果 ### 标题级别的标题使用动名词，即以“-ing”结尾的词，例如“安装”，那么请尝试使用动名词编写该标题级别下的所有标题。如果标题以祈使动词开头，例如“使用”、“配置”，则编写该标题级别下所有以祈使动词开头的标题。
  • 避免在较低级别的标题中使用常见术语：不要在较低级别的标题的标题中重复较高级别标题中的文本。例如，在一个标题为“逗号”的部分中，将子部分的标题命名为“引导从句之后”，而不是“引导从句之后的逗号”。
  • 不要以冠词开头：避免以冠词“a”、“an”或“the”开头标题。
  • 添加引导信息：在标题之后，添加一些介绍性文本以解释将在该部分中介绍的内容。

• 编写代码示例的指南
• 编写 HTML 代码示例的指南
• 编写 CSS 代码示例的指南
• 编写 JavaScript 代码示例的指南
• 编写 shell 提示符代码示例的指南

如果您对此处未涵盖的用法和样式有任何疑问，我们建议您参考 Microsoft Writing Style Guide 或 Chicago Manual of Style。

如果您有兴趣提高您的写作和编辑技能，您可能会发现以下资源很有帮助。

• 英语常用错误 on brians.wsu.edu
• 英语语法常见问题解答 on alt-usage-english.org
• 英语语言和用法 on english.stackexchange.com：英语语言用法的问答网站
• Merriam-Webster's Concise Dictionary of English Usage on google.com/books (published 2002)：学术性但用户友好，基于证据的建议；非常适合非母语人士，尤其是在介词用法方面
• On Writing Well by William Zinsser on harpercollins.com (published 2016)
• Style: Lessons in Clarity and Grace by Joseph Williams and Gregory Colomb on google.com/books (published 2019)