WordPress 贡献者寻求赞助以改进 Gutenberg 开发人员文档

WordPress 开发人员 Milana Cap 和 Jonathan Bossenger 开始筹款以改进 Gutenberg 开发人员文档。 谈话开始于昨天，当 Cap 发布推文时，当公司雇用全职贡献者在 WordPress 上工作时，文档经常被忽视。

“当你的社区无法学习你的软件时，你就没有贡献者了，”Cap 说。 “对于开源软件项目来说，文档和教程比人们意识到的要重要得多。”

Cap 第一次开始要求提供 Gutenberg 文档是在 2017 年巴黎的社区峰会上。从那时起，她一直试图将社区的注意力引向它。

“开发人员的块编辑器文档中有很多漏洞，但最明显的是如何开始，”Cap 说。 “开发人员文档的开头并没有说明入门。 “它只说明了你可以用一个块做什么，而不是_how_。 初级开发人员、纯 PHP 开发人员以及该文档所针对的任何人，不知道块代码的外观、放置位置、如何包含它等，更不用说如何使用自定义组件构建自定义块和设置。”

记录块编辑器的部分挑战在于它正在积极开发中。 Gutenberg 插件不断地进行增强和改进，跟踪核心中当前可用或不可用的内容并不总是那么容易。 由于 WordPress 即将引入块目录搜索，现在是正式化块创建文档的好时机。

“代码示例在整个文档中都出现了惊人的缺失，”Cap 说。 “最基本的例子是存在的，但缺少如何实际构建可用的东西。 因此，在第一页上，我们被发送到一个教程，但该教程并未针对以前从未构建过块的人进行优化。 跟随它，我已经并且将无法构建块。”

Marcus Kazmierczak 和一个文档贡献者团队正在尝试重建官方块编辑器手册中的教程。 一个 GitHub 问题专注于解决当前开发人员文档中的差距，这是一个积极讨论的地方，该问题是关于为新阻碍开发的人重写文档的最佳方法的。

“这是一个非常好的开始，但仍有许多工作要做，”Cap 说。 “完整的文档是由了解和理解 React 和 Gutenberg 但被‘知识诅咒’的人编写的。 他们没有太多时间花在了解其他人不知道多少以及应该编写哪些详细文档上。 老实说，我认为他们不应该把时间花在这上面。 我们有一个文档团队，我们愿意加入，但某种桥梁是必要的。”

Gutenberg 开发者文档的问题：对新手不友好

“我在块编辑器文档中看到的'问题'是，与其他 WordPress 文档不同，它是为有经验的 JavaScript 开发人员编写的，而不是针对初学者，”Bossenger 说。 “我还应该指出，这绝不是对那些将当前文档放在一起的人的看法，我感谢他们迄今为止所做的所有工作，只是非常需要审查和一些改进。 ”

Bossenger 过去曾表示，WordPress 让任何对 PHP 知识有限的人都​​可以非常轻松地使用操作和过滤钩子快速构建插件或主题。 查看代码并理解它应该做什么很容易。

“现代 JavaScript，特别是 React，是一种非常不同的鱼，”Bossenger 说。 “它需要更深入地了解 React 的工作原理，包括新的术语和实践。 现代 JavaScript 也可能非常令人困惑，特别是如果这是您第一次看到箭头函数或不那么冗长的 if 语句之类的东西。

“如果您在 WordPress 中最接近使用 JavaScript 的一直是使用 jQuery，那么切换到基于 React 的 Gutenberg 开发仍然需要您学习一些知识。”

Bossenger 在为编辑器构建任何东西之前学习了两门课程，一门关于 React，一门关于 Gutenberg，他说当前的 Block Editor 手册不是为没有 React 和现代 JavaScript 经验的开发人员编写的。 他认为它需要重组以更好地解释新概念并适应新人更容易消费的模式。 他以 Plugin Developer 手册为例，其中章节遵循一种结构并使用更像教科书的术语，慢慢地向读者介绍新概念。

“我认为，对于没有插件或 PHP 知识的人来说，拥有这本手册和谷歌，很可能构建一个简单的插件来很快满足他们的特定要求，”Bossenger 说。 “目前区块编辑器手册不利于这一点。”

Bossenger 对当前文档的看法并不孤单。 Delicious Brains 的 Peter Tasker 最近发布了关于创建自定义 Gutenberg 块的教程。 即使在过去一年全职使用 React 之后，他发现官方的块编辑器文档“有点到处都是”并且难以解析。

在 Cap 评论缺乏赞助全职文档工作的公司之后，Bossenger 试水了一条推文，询问他们两人是否能够筹集资金来改进 Gutenberg 文档。

“就像块编辑团队（和任何其他制作团队）一样，文档团队人手不足，”Cap 说。 “我们不能让少数成员先学习然后编写有关使用块编辑器进行开发的文档。 这是我发推文的主要原因。 你会看到赞助的贡献者遍布核心，但不是在文档中，我敢说两者同样重要。”

在启动他们的筹款活动之前，Cap 和 Bossenger 计划检查现有的文档，找出明显的漏洞，并找出对于那些刚开始为块编辑器开发的人来说仍然没有答案的问题。

“一旦我们制定了计划，我们就可以预测每个部分需要多少时间，”她说。 “有了这个计划，我们将寻找赞助商。 我认为在此之前会有捐赠的选择，但目前还不确定。”

块是 WordPress 开发的新前沿。 为初学者投资可靠的文档和教程可能会对扩展区块生态系统产生重大影响。 这也间接地使用户受益，因为他们最终在自定义 WordPress 网站时可以选择更多样化的块目录。

Bossenger 和 Cap 目前正在为文档制定计划，然后宣布他们的筹款活动。 与此同时，任何想为改进区块创建文档做出贡献的人都可以加入 GitHub 讨论。