MDN Web文档发展：即将推出的新平台上的底层

Kuma--支持MDN Web Docs的平台--发展的时候到了。很长一段时间以来，MDN开发团队一直在计划一个彻底的平台改变，我们已经准备好开始分享它的细节。你嘴唇上的问题可能是“Kuma进化成了什么？”一个KumaMama？“。

对于那些不是很喜欢精灵宝可梦的人来说，问题可能是“MDN到底是如何改变的，它对MDN用户和贡献者有什么影响？”

对于普通用户来说，答案很简单-我们为您提供每天用于学习和工作的伟大内容的方式几乎没有什么变化。

简而言之，我们正在更新平台，将内容从MySQL数据库转移到GitHub存储库(代号：Project Yari)。

更少的开发者维护负担：现有的库马(Kuma)平台复杂且难以维护。添加新功能非常困难。这次更新将极大地简化平台代码-我们估计我们可以删除大量现有的代码库，这意味着更容易维护和贡献。

更好的贡献工作流程：我们将使用GitHub的贡献工具和功能，实质上是将MDN从Wiki模型迁移到Pull Request(PR)模型。这对于贡献来说要好得多，允许智能绑定、批量编辑，并将MDN文档包含在您想要添加到的任何工作流中(您可以直接在您最喜欢的代码编辑器中编辑MDN源文件)。

更好的社区建设：目前，MDN内容编辑会立即发布，如果不合适则会恢复。这对社区关系真的很不好。有了公关模式，我们可以审查编辑并提供反馈，实际上与贡献者进行对话，与他们建立关系，并帮助他们学习。

改进的前端架构：现有的MDN平台有许多前端不一致和可访问性问题，我们想要解决这些问题已经有一段时间了。迁移到新的、简化的平台为我们提供了解决此类问题的绝佳机会。

该平台的具体形式尚未最终确定，我们希望让您社区参与帮助提供想法并测试新的投稿工作流程！我们将在11月2日准备好新平台的测试版进行测试，第一个版本将在12月14日发布。

我们正在用JAMStack方法取代当前的MDN Wiki平台，JAMStack方法发布在GitHub repo中管理的内容。与现有的Wiki平台相比，这有很多优势，这是我们多年来一直在考虑的。

在讨论我们的新方法之前，让我们回顾一下Wiki模型，以便更好地理解我们正在进行的更改。

值得注意的是，内容贡献者(作者)和内容查看者(读者)都通过相同的体系结构提供服务。该架构必须适应这两种用例，即使我们99%以上的流量包括来自读者的文档页面请求。目前，当请求文档页面时，会从MySQL数据库中读取文档的最新版本，将其呈现为最终的HTML形式，然后通过CDN返回给用户。

该文档页面将在接下来的5分钟内从CDN的缓存中存储和提供，因此，只要后续请求在这5分钟的窗口内，CDN就会直接为其提供服务。5分钟的缓存期被故意保持得很短，这主要是因为我们需要满足编写者的需求。如果我们只需要满足读者的需求，我们就可以显著增加缓存期，更快地为文档页面提供服务，同时减少后端服务器上的工作负载。

您还会注意到，因为MDN是一个Wiki平台，所以我们负责管理所有内容，以及存储文档修订、显示文档修订历史、显示修订之间的差异等任务。目前，MDN开发团队维护着大量专门用于这类任务的代码。

使用新的JAMStack方法，写入者和读取者是分开服务的。写入者通过GitHub存储库和拉入请求模型管理文档内容，而读者则通过从S3通过CDN提供的预先呈现的文档页(这将具有更长的缓存期)更快、更高效地获得文档页。我们的GitHub存储库的文档内容将每天呈现并部署到S3。

从上图中您会注意到，即使使用这种新方法，我们仍然拥有一个Kubernetes集群，其中基于Django的服务依赖于关系数据库。需要记住的重要一点是，系统的这一部分不再涉及文档内容。它的范围已经大大缩小，现在它的存在完全是为了提供与用户帐户(例如登录)和搜索相关的API。

这种关注点分离有多个好处，其中最重要的三个好处如下：

首先，文档页面以最简单、最快捷、最高效的方式提供给读者。这真的很重要，因为MDN 99%的流量是面向读者的，而全球性能是用户体验的基础。

其次，因为我们使用GitHub来管理文档内容，所以我们可以利用GitHub作为内容管理系统必须提供的世界级功能，并且我们不再需要支持与我们当前的Wiki平台相关的大量代码。只需将其删除即可。

第三，也许不那么明显的是，这种新方法为平台带来了更多的功能。例如，我们可以对每个内容拉取请求执行自动绑定和测试，这使我们能够更好地控制质量和安全性。

由于MDN内容很快就会包含在GitHub资源库中，因此投稿工作流程将发生重大变化。您将无法再单击页面上的“编辑”，进行并保存更改，并使其几乎立即显示在页面上。您也将不再能够在所见即所得编辑器中进行编辑。

相反，您将需要使用Git/GitHub工具进行更改，提交Pull请求，然后等待更改被合并、新构建被部署等等。对于非常简单的更改，如修复打字错误或添加新段落，这可能看起来像是后退-Kuma对于这样的编辑和非开发人员贡献者来说肯定是方便的。

然而，对于Yari来说，做一个简单的改变可以说并不复杂。您可以使用GitHub UI的编辑功能直接编辑源文件，然后提交PR，这意味着您不必是GIT天才才能贡献简单的修复。

对于更复杂的改变，你需要使用git CLI工具，或者像GitHub Desktop这样的GUI工具，但是话说回来，git在网络行业是如此普遍的工具，所以可以肯定地说，如果你对编辑MDN感兴趣，你可能需要在一定程度上了解git作为你的职业或课程。如果您还不了解git，您可以将其作为学习git的好机会！最重要的是，需要学习文件系统结构，需要习惯一些新的工具/命令，但不会非常复杂。

要提到的另一个可能的挑战是，当您添加内容时，您不会有一个所见即所得(WYSIWYG)来立即看到页面的外观，此外，您将编辑原始的HTML，至少在开始时是这样(我们正在讨论最终将内容转换为标记，但这有点不太可能)。同样，这听起来像是倒退了一步，但是我们在repo中提供了一个工具，以便您可以在本地构建和预览完成的页面，以确保它在您提交Pull请求之前看起来是正确的。

考虑到现在的优势，可以认为将MDN内容作为GitHub回购提供是一件非常强大的事情。我们不再有垃圾内容活在网站上，然后我们必须在事后恢复更改。您还可以自由地以最适合您的方式编辑MDN内容-您最喜欢的IDE或代码编辑器-并且您可以将MDN文档添加到您的首选工具链中(并编写您自己的工具来编辑您的MDN编辑体验)。许多工程师过去曾告诉我们，如果他们能够提交Pull请求，而不必使用WYSIWYG，他们会更乐意为MDN文档做贡献！

我们还在研究一个强大的工具集，该工具集将允许我们增强审查过程，例如，作为CI过程的一部分-自动检测并关闭垃圾公关，如前所述，一旦页面被编辑，就将页面链接起来，并向编辑提供反馈。

将MDN放在GitHub repo中还可以提供更容易的大规模编辑；以前更改全面内容非常困难。

最后，“生存时间”应该是可以接受的-我们的目标是在审查过程中迅速扭转局面，部署过程将每24小时重复一次。我们认为，在最坏的情况下，您的更改应该在48小时内在网站上生效。

目前，就其社区而言，MDN并不是一个非常活跃的地方。我们有一个相当活跃的学习论坛，人们可以在那里询问初学者编码问题并寻求评估方面的帮助，但实际上并没有一个活跃的地方让MDN工作人员和志愿者定期聚在一起讨论文档需求和贡献。

这在一定程度上要归功于我们的贡献模式。当您编辑mdn页面时，要么您的投稿被接受而您什么也听不到，要么您的投稿被恢复并且您被…。我什么都没听到。您只能通过查看您的编辑是粘滞的、反编辑的还是还原的，才能知道这两种方式中的哪一种。

这给我们的印象不是很友好，我想你可能会同意。当我们转向git公关模式时，MDN社区将能够提供实际帮助，帮助人们正确做出贡献-在我们审查他们的公关时提供帮助(如前所述，还提供自动帮助)-并感谢人们的帮助。

对于贡献者来说，显示他们已经做出了多少贡献也会容易得多，我们将添加页面内链接，允许人们在特定页面上提交问题，甚至如果遇到问题，可以直接转到GitHub上的源代码并自行修复。

就寻找一个谈论MDN内容的好地方而言，您可以加入Matrix上的MDN Web Docs聊天室的讨论。

旧的Kuma架构有许多前端问题。从历史上看，我们缺乏一个定义良好的系统来清楚地描述我们需要在其中工作的约束，以及我们的站点功能是什么样子的，这导致我们最终拥有一个臃肿的、难以维护的前端代码库。使用我们当前的HTML和CSS就像坐在没有护栏的过山车上。

需要明确的是，这不是任何一个人的错，也不是MDN项目生命周期中任何特定时期的错。随着时间的推移，有许多小东西会溃烂、繁衍和腐烂。

可访问性：现有架构中确实有许多可访问性问题需要解决，但由于Kuma的复杂性，这些问题很难解决。

组件不一致：Kuma没有使用适当的设计系统-类似的项目在整个站点以不同的方式实现，因此实现功能比需要的要困难得多。

当我们开始推进后端平台重写时，感觉现在是再次提出设计系统的想法的绝佳时机。经过多次对话，最终达成了一个可以接受的折衷方案，我们的设计系统-MDN Fiori诞生了。

前端开发人员Schalk Neethling和UX设计人员Mustafa Al-Qinneh对MDN参考文档的核心进行了一次旋风式的访问，以识别组件并记录我们正在处理的所有不一致。作为这项工作的一部分，我们还寻找可以改善用户体验的领域，并通过对整体设计的一些核心底层方面进行微小更改来引入一致性。

这包括定义好的调色板、基于定义明确的字体比例的简单、整洁的排版、一致的间距、改进了对移动和平板设备的支持，以及许多其他小调整。这从来不是对MDN的重新设计，所以我们必须小心不要做太多更改。相反，我们发挥了现有的优势，使流氓样式和标记与整个项目保持一致。

除了视觉一致性和总体用户体验方面，我们的底层代码库需要一些严肃的关爱和关注-我们决定彻底重新考虑。在这个过程的早期，很明显我们需要一个小的、灵活的和最小的基础库。一些独特的MDN，但它可以在任何需要MDN品牌核心方面的地方重复使用。为此，我们创建了MDN-Minimist，这是一个小的核心原子集合，以一种逐步增强的方式为MDN的基础样式提供动力，利用了我们今天在Web上访问的漂亮的新布局系统。

Yari中内置的每个组件都带有MDN-Minimist样式，并且还具有自己的样式表，该样式表仅在需要时才会应用进一步的样式。这是一个不断发展的过程，因为我们不断地重新思考如何在尽可能接近网络平台的同时提供出色的用户体验。原因有两方面：

首先，这意味着更少的代码。这意味着减少轮子的重新发明。这意味着我们的最终用户将拥有更快、更精简、占用带宽更少的MDN。

其次，它有助于解决一些我们已经勉强忍受了一段时间的可访问性问题，这些问题在现代网站上是不可接受的。Mozilla的一位可访问性专家Marco Zehe给了我们很多帮助我们克服这些问题的意见。我们不会在第一次迭代中解决所有问题，但我们对所有用户的承诺是，我们将继续改进，并欢迎您就我们可以进一步改进的领域提供反馈。

一位智者曾经说过，确保某事做对的最好方法就是让做正确的事变得容易。因此，除了已经提到的所有工作之外，我们还在Storybook中记录我们的前端代码库、设计系统和模式库(请参阅Yari repo中的Storybook文件)，同时在Figma中记录相应的设计工作(请参阅排版示例)，以确保希望从代码或设计角度为MDN做出贡献的任何人都有一个简单的、公开的参考资料。这本身就是一个巨大的项目，将随着时间的推移而发展。关于其演变的更多交流将随之而来。

MDN内容的一个重要部分，我们在规划阶段已经讨论了很多，那就是本地化内容。您可能已经知道，MDN提供了翻译原始英文内容并提供本地化的工具。

原则上这是好的，但是现在的制度有很多缺陷。当一个英文页面被移动时，所有的本地化都必须单独移动，因此页面和它们的本地化经常不同步，并且变得一团糟。一个更大的问题是，没有简单的方法来通知所有本地化的人都改成了英文版本。

一般管理可能是最重要的问题。你通常会对某一地区产生热情，并完成大量的翻译工作。但几个月后，人们的兴趣就消退了，没有人留下来让翻译保持最新。本地化内容变得过时，这通常对学习有害，成为耗时的维护工作，因此，人们通常认为没有本地化内容比没有本地化内容更糟糕。

请注意，我们并不是说MDN上的所有地区都是如此，我们也不是试图淡化志愿者在创建本地化内容方面所投入的工作量。为此，我们永远心存感激。但事实仍然是，我们不能继续这样下去。

我们做了大量的研究，并与许多非英语母语的网站开发人员讨论了什么对他们有用。得出了两个有趣的结论：

如果我们取消或减少本地化支持，我们将经历大量但可管理的用户流失。8种语言覆盖了从MDN用户接收的接受语言标头的90%(en、zh、es、ja、fr、ru、pt、de)，而14种语言覆盖了95%的接受语言。我们预测，如果完全放弃L10n，预计最多会损失19%的流量。

机器翻译即使不是完美的，也是大多数情况下可以接受的解决方案。我们观察了谷歌翻译(Google Translate)等自动化解决方案提供的翻译质量，并让一些社区成员将这些翻译与手动翻译进行了比较。机器翻译是不完美的，有时很难理解，但许多人评论说，一种不完美的语言是最新的，而不是一种完美的语言是过时的。我们理解一些语言(如中日韩语言)在自动翻译方面不如其他语言。

那我们怎么决定的？随着新平台的最初发布，我们计划包括当前所有文档的所有翻译，但处于冻结状态。翻译将存在于他们自己的MDN/翻译内容存储库中，我们不会接受任何拉入请求。翻译将显示一个特殊的标题，上面写着“这是一个存档的翻译”。不再接受编辑。“。这是一个暂时的阶段，直到我们想出下一步。

注意：此外，UI组件和标题菜单的文本将仅为英文。它们不会被翻译，至少一开始不会。

在最初发布之后，我们希望与您(社区)合作，找出推进翻译工作的最佳行动方案。理想情况下，我们不希望丢失MDN上的本地化内容，但我们需要修复过去的技术问题，更好地管理它，并确保内容保持最新。

我们将按照以下指导原则规划下一阶段的MDN本地化：

在很大范围内手动本地化所有MDN内容似乎是不可行的，所以我们应该放弃这种方法。

我们还没有就可交付成果或时间框架做出承诺，但我们已经开始沿着以下思路思考：

将我们正在处理的区域数量减少到前14个区域，这些区域提供了我们记录的接受语言标头的95%。

最初包括“第一层”MDN内容页面的不可编辑的基于机器学习的自动翻译(即一组最重要的MDN内容，它排除了没有或几乎没有查看的文章的大量长尾)。理想情况下，我们希望使用现有的手动翻译来训练机器学习系统，希望能获得更好的结果。这很可能是我们在2021年要做的第一件事。

开始提供一个系统，允许社区成员通过手动编辑改进自动翻译。这将要求社区确保文章在更新时与英文版本保持同步。

正如我们前面提到的，我们将在11月2日启动新MDN平台的测试版测试。我们希望您能帮助我们测试新的系统和贡献工作流程，让我们知道哪些方面看起来很好，哪些方面看起来很痛苦，并提出改进建议。

如果您希望在新系统准备好测试时收到通知，请使用此表格通知我们。

我要感谢我的同事Schalk Neethling，Ryan Johnson，Peter Bengtsson，Rina Tambo Jensen，Hermina Condei，Melissa Thermidor，以及其他我已经忘记的人，他们帮助我完善了这篇文章，提供了一些内容，反馈，评论，编辑等等。