许多东西都归功于阿尔伯特·爱因斯坦，但他可能从未说过的话中，似乎有一句是固定的：

如果你不能简单解释，那么你对它的理解还不够充分。

当这种说法应用到向人们解释新想法时，你希望加入 Joomla 核心的新特性，简单性通常是一个好的开始。

但简单性很难实现。当我们看到优秀的设计、代码和发明时，会有一个被丢弃的想法、线条和原型堆砌的墓地，它们是建立在其上的。

有很多工艺将初生的想法从粗糙的想法转变为经过深思熟虑的完整特性。
一旦你磨炼了那个新的必需的想法，接下来就是测试、编写和描述用例的问题。

但我们真的需要写这样的文档吗？我们应该浪费时间解释和描述吗？最好继续进行下一个伟大的新特性，做程序员最擅长的事情... 编码。

这就是我们面临的问题。程序员不一定就是写作者、测试员甚至不是母语英语的人。
仅仅因为代码是用英语单词编写的，并不意味着创作者精通默认语言。所以那些“将来会写”的文档从未被编写，那些专门的手动编写的日子从未到来，我们也没有得到应有的思想见证。

没有好的文档会发生什么

所以测试员没有得到他们应该有的简单易懂的测试。特性没有得到成为核心的一部分所需的测试，而想法在队列中长时间滞留。

如果最终它做到了，那么文档编写者需要做的是弄清楚它做什么，它是如何做到的，以及为什么它应该成为 Joomla 核心的一部分。没有这些内部知识，理解别人的工作、支持想法并做到公正真的非常困难和耗时。

时间流逝，有人需要这个功能，它悄无声息地进入了核心，隐藏起来，只有少数人使用，于是另一位程序员想出了一个绝妙的主意，创建了一个扩展，它恰好实现了核心功能，仅仅因为他们没有意识到这一点。

这种情况确实发生了。我怎么会知道？因为我曾经经历过，写过这样的代码，只是后来发现它已经在核心里了，只是被隐藏了起来。

这是现代版的古老谚语，“差之毫厘，谬以千里”。
有很多版本，这是DC漫画版的。

因为缺少一颗钉子，鞋子丢了；
因为缺少鞋子，马匹丢失；
因为缺少马匹，骑士失落；
因为缺少骑士，战斗失败；
因为缺少战斗，王国失落。
所以王国失落——都是因为缺少一颗钉子。

文档就像我们常说的那颗钉子：一切取决于良好的文档。其余所需的内容将顺理成章。

良好的文档会发生什么

有了良好的文档，当代码首次出现在GitHub上时，可以编写有意义的测试，安装和使用功能的说明也将更容易。

如果测试说明更容易理解，那么不仅功能可以更快地得到测试，而且测试的质量也会更高，测试得更深入，可以揭示一些可能并非故意设计的内容，并在早期进行修复和改进。

在他们的一个高效且从不偏离主题的规划会议上，杂志团队将安排采访功能编码员和说明书的撰写者，以获得全面的洞察。
这篇文章将在功能发布之前出现，以便所有人都能了解如何以及何时使用它。

然后，压力山大的文档团队将欣喜若狂，因为他们有当代的优秀、详细、详尽的信函可以提取并放置在正确的位置。

好吧，但我们如何解决这个问题呢？

那么，这个神奇的秘方将会如何戏剧性地改变我们目前做事的方式，你可能会问？

介绍文档伙伴。

一群愿意与任何功能编码员会面并讨论、理解他们计划的作家。有人可以将代码想法翻译成一篇良好的、图文并茂的文章，这篇文章可以从GitHub上的想法描述开始，在写作过程中逐步发展成Joomla生态系统各个领域的结构和形式。

与某人讨论功能的过程本身就可以真正帮助发展涉及到的想法。这样的作家可以帮助提供一个系统的方式来记录要包含的功能。

需要讨论和详细说明的领域包括

• 我们为什么需要这个功能？
• 它将帮助我们解决哪些用户案例？
• 如果它在管理员和站点侧都有影响，我们将在哪里遇到它？
• 我们如何安装和如何使用它？
• 配置细节，如何设置以及这种配置的范围？
• 测试，如何进行测试以及测试的明确结果，以便它容易被理解和检验？
• 任何副作用，当前行为中可能不期望的变化。
• 任何第三方资源。

一旦讨论完毕，文档伙伴对所涉及的内容有了理解，就应该进行几个功能想法的草案，以便编码员和文档作家完全处于同一页面上。

通过这个更详细的说明，GitHub上的对话应该会更有信息量。GitHub的反馈也可以帮助根据其他人在精炼过程中的见解和建议来塑造文档的一些部分。

然后，当它经过测试并标记为包含时，GitHub中的写作可以成为杂志文章和任何需要编写的文档的基础。

杂志文章应该全面阐明该功能，让更广泛的社区受益，并在JUG（Java用户组）演讲中传播信息。

因此，我不再只是展示一个我在一个下午偶然拼凑起来的小巧功能，然后在Joomla伦敦用户组被告知它已经在核心中隐藏。

我想成为其中的一员！怎么才能做到呢？

现在，亲爱的读者，轮到你了。如果你想到“是的，这正是需要的”和“如果它一直像那样工作就好了”，那么请不要担心！你可以成为其中的一员，你可以加入使用写作力量来提升他人编写的代码的文档编写者群体。
在Glip上有一个名为“文档伙伴”的新组建来从事这项工作。

我们希望保持其有趣和高效，有帮助和协作。所以来加入我们，联系此电子邮件地址已受到反垃圾邮件软件的保护。您需要启用JavaScript才能查看。如果您需要访问频道并成为解决方案的一部分。

本文的法语翻译： accompany the documentation - improve Joomla without writing a line of code https://www.joomla.fr/actualites/accompagner-la-documentation-ameliorer-joomla-sans-ecrire-une-ligne-de-code