为 MDN 网络文档做贡献

MDN Web Docs 已经记录了 Web 平台超过 12 年，现在是一个跨平台的工作，有来自谷歌、微软和三星以及代表 Firefox 的成员的贡献和顾问委员会。 MDN 的基础是它是一个巨大的社区努力，网络社区帮助创建和维护文档。 在本文中，我将为您提供一些关于您可以帮助为 MDN 做出贡献的地方以及具体如何做的建议。

如果您之前没有为开源项目做出过贡献，那么 MDN 是一个很好的起点。 需要的技能范围包括编辑、从英语翻译成其他语言、创建交互式示例的 HTML 和 CSS 技能，或者对更新浏览器兼容性数据的浏览器兼容性感兴趣。 您不需要做的是编写大量代码来贡献。 如果您发现这些文档很有用，这非常简单，也是回馈社区的绝佳方式。

贡献给文档页面

您可能想要贡献的第一个地方是 MDN 文档本身。 MDN 是一个 wiki，因此您可以登录并开始通过更正或添加任何 CSS、HTML、JavaScript 或 MDN 涵盖的 Web 平台的任何其他部分的文档来提供帮助。

要开始编辑，您需要使用 GitHub 登录。 与 wiki 一样，页面的任何编辑器都会被列出，此部分将使用您的 GitHub 用户名。 如果您查看页面底部列出的 MDN 贡献者的任何页面，下图显示了 CSS 网格布局页面的当前贡献者。

你可以编辑什么？

作为编辑，您可能会考虑修复明显的拼写错误和语法错误。 如果您是一名优秀的校对员和文案编辑员，那么您很可能可以通过修复您发现的任何拼写或其他错误来提高文档的可读性。

您可能还会发现技术错误，或者规格发生变化的地方以及更新或澄清有用的地方。 凭借 MDN 涵盖的大量 Web 平台功能和变化率，如果您发现某些东西，很容易过时 - 修复它！

您也许可以使用一些您必须添加的特定知识来添加附加信息。 例如，Eric Bailey 一直在向许多页面添加可访问性问题部分。 这是一项出色的工作，旨在突出我们在使用特定事物时应该考虑的事情。

您可以添加到页面的另一个地方是添加“另请参阅”链接。 这些可能是指向 MDN 其他部分或外部资源的链接。 添加外部资源时，这些资源应该与该文档所描述的属性、元素或技术高度相关。 一个好的候选者将是一个演示如何使用该功能的教程，这将为搜索信息的读者提供有价值的下一步。

如何编辑文档？

登录后，您将在 MDN 的页面上看到一个编辑链接，单击此链接将带您进入所见即所得的编辑器以编辑内容。 您的前几次编辑可能是很小的更改，在这种情况下，您应该能够随心所欲地编辑文本。 如果您正在进行大量编辑，那么值得先查看样式指南。 还有一个使用 WYSIWYG 编辑器的指南。

进行编辑后，您可以预览然后发布。 在发布之前，最好解释一下您添加的内容以及使用“修订注释”字段的原因。

语言翻译

我们这些以英语为第一语言的人在网络信息方面非常幸运，能够以我们自己的语言获得几乎所有我们想要的信息。 如果您能够将英语页面翻译成其他语言，那么您可以帮助翻译 MDN Web Docs，让更多人可以使用所有这些信息。

如果您单击任何页面上的语言图标，您可以看到该信息已被翻译成哪些语言，并且您可以在翻译 MDN 页面页面上的信息之后添加自己的翻译。

交互式示例

MDN 上的交互式示例是您将在 MDN 的许多页面顶部看到的示例，例如grid-area属性的示例。

这些示例允许 MDN 的访问者在 MDN 上尝试各种 CSS 属性值或尝试 JavaScript 函数，而无需进入开发环境即可。 添加这些示例的项目已经进行了大约一年，您可以在将交互式示例带到 MDN 的帖子中了解该项目和迄今为止的进展。

这些交互式示例的内容保存在交互式示例 GitHub 存储库中。 例如，如果您想找到 grid-area 的示例，您可以在live-examples/css-examples/grid下的那个 repo 中找到它。 在该文件夹下，您将找到两个用于grid-area的文件，一个 HTML 和一个 CSS 文件。

网格区域.html

 <section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>

grid.area.css

 .example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }

交互式示例只是一个小演示，它使用了一些标准的类和 ID，以便框架可以选择示例并使其具有交互性，其中值可以由想要快速查看它的页面的访问者更改作品。 要添加或编辑交互式示例，首先 fork 交互式示例存储库，将其克隆到您的计算机上，然后按照贡献页面上的说明从 npm 安装所需的包，并能够在本地构建和测试示例。

然后创建一个分支并编辑或创建您的新示例。 一旦您对它感到满意，请向 Interactive Examples 存储库发送一个 Pull Request，要求对您的示例进行审查。 为了使示例保持一致，评论是相当挑剔的，但应该以清晰的方式指出您需要进行的更改，以便您可以更新您的示例并使其获得批准、合并并添加到 MDN 页面。

现在几乎涵盖了所有的 CSS（除了 JavaScript 示例），MDN 现在正在寻求帮助来构建 HTML 示例。 MDN Discourse 论坛上的帖子中有关于如何开始的说明。 查看该帖子，因为它提供了指向 Google 文档的链接，您可以使用该链接来表明您正在处理特定示例，以及其他一些有用的信息。

交互式示例对于探索 Web 平台的人们非常有用，因此添加到项目中是一种极好的贡献方式。 贡献 CSS 或 HTML 示例需要 CSS 和 HTML 知识，以及想出清晰演示的能力。 最后一点通常是最难的部分，我创建了很多 CSS 交互示例，并且花费更多时间为每个属性考虑最佳示例，而不是实际编写代码。

浏览器兼容数据

最近，MDN 页面上列出的浏览器兼容性数据已开始通过浏览器兼容性项目进行更新。 本项目正在开发 JSON 格式的浏览器兼容性数据，它可以显示 MDN 上的兼容性表，也可以作为其他用途的有用数据。

Browser Compatibility Data 在 GitHub 上，如果您发现页面信息不正确或仍在使用旧表，您可以提交 Pull Request。 存储库包含贡献信息，但是，最简单的开始方法是编辑现有示例。 我最近更新了 CSS shape-outside属性的信息。 该属性已经有一些新格式的数据，但它不完整且不正确。

为了编辑这些数据，我首先对 Browser Compat Data 进行了 fork，这样我就有了自己的 fork。 然后我将它克隆到我的机器上并创建了一个新分支来进行更改。

有了新分支后，我找到了shape-outside的 JSON 文件，并且能够进行编辑。 我已经对该属性的浏览器支持有了一个好主意； 当我不确定时，我还使用 shape-outside MDN 页面上的实时示例进行测试以查看支持。 因此，进行编辑需要处理文件，检查列出的版本号以支持该属性并更新不正确的版本。

由于该文件是 JSON 格式，因此在任何文本编辑器中编辑都非常简单。 .editorconfig 文件解释了这些文档的简单格式规则。 此清单中还有一些有用的提示。

完成编辑后，您可以提交更改，将分支推送到 fork，然后向 Browser Compat Data 存储库发出拉取请求。 与实际示例一样，审阅者很可能会对您进行一些更改。 在我的 Shapes 数据 PR 中，我在如何标记数据时遇到了一些错误，需要对链接进行一些更改。 这些很容易制作，然后我的 PR 被合并了。

开始使用

在许多情况下，您只需选择要添加的内容并开始工作即可开始。 如果您对此有任何疑问或需要任何帮助，那么 MDN Discourse 论坛是发帖的好地方。 MDN 是我查找信息的地方，是我发送新开发人员和经验丰富的开发人员的地方，它的优势在于我们都可以努力让它变得更好。

如果您以前从未对项目提出过拉取请求，那么在此进行第一次 PR 是一个非常友好的地方，并且正如我希望我已经展示的那样，有一些贡献方式根本不需要编写任何代码。 对于任何文档项目来说，一个非常有价值的技能是写作、编辑和翻译，因为这些技能可以帮助世界各地的更多人更容易阅读和访问技术文档。