Joomla 文档内容丰富，任何人都可以轻松参与贡献。多年来，Joomla 文档 Wiki 已经显著增长，这本身是好事，但也带来了挑战。

 它缺乏结构，难以搜索，包含大量过时的文章，且文档翻译并不像应有的那样直接。因此，是时候重新考虑我们的文档工具了。如果我们能够拥有一个基于 Joomla 的文档解决方案会怎样呢？

Jdocmanual 是一个定制组件，旨在作为 概念验证，以提高易用性、易贡献性、易翻译性和易管理性。它将 Joomla 文章以 手册 格式集合起来，正如许多其他软件文档项目中所见：左侧的文章索引、中间的文章文本和右侧的文章内容。这种呈现方式是简单的部分！本文主要介绍如何在 Jdocmanual 中满足其他 简单 的需求。它的目的是为关于 Joomla 文档未来的讨论做出贡献。

您可以亲自尝试公开视图： https://jdocmanual.org。这就是管理员视图中的样子

网站视图与此类似，但没有左侧菜单。用户可以选择任何可用的手册，并在任何可用的语言中显示索引和/或内容。

源数据

Jdocmanual 的文章已从 docs.joomla.org 选择，这是用于 Joomla 文档的 MediaWiki 安装。仅包括与 Joomla 4 相关的文章，并且每篇文章都已转换为 GitHub Flavoured Markdown。文章已组织成针对不同用户组的单独手册：用户、开发者、文档者和帮助。以后可以添加其他内容，例如从 Joomla 社区杂志中选择的教程。

更新数据

Jdocmanual 可由两个用户组中的多个贡献者共同编辑：一个 JDM 作者可以为编辑目的创建一篇文章的个人副本；一个 JDM 发布者可以将 JDM 作者（在此处用于表示与 Joomla 默认作者和发布者不同的用户组）创建的更改提交。发布者也拥有作者的权限。可用的文章列表始终基于源英语列表。这是选择除英语以外的语言时文章列表的截图

在 已翻译 列表中的勾选标记表示该特定文章已被翻译成所选语言。没有勾选标记的尚未翻译。如果选择英语，则不显示此列。在状态列中，存档：1 表示用户已创建一个个人存档来编辑该文章。黄色 新建存档 按钮表示我可以为该文章创建一个自己的个人存档来编辑。绿色 编辑存档 按钮表示我已经创建了一个个人存档来编辑该文章。

新建页面 必须使用英语创建，因此只有在选择英语时工具栏中才会出现 新建 按钮。此外，新页面不能出现在页面列表中，因为它们仅作为存档存在，直到提交。因此，新建页面 选项卡显示了所有正在准备中的新页面。

我的存档 是一个用于显示我创建的任何存档列表的选项卡。

拉取请求 是只有 JDM 发布者组用户才能看到的选项卡。列表包括所有用户的拉取请求。此列表中的链接将打开作者使用的相同的存档编辑表单，但它有一个额外的标签栏按钮，标签为 提交。

编辑内容

以下截图显示了存档编辑表单中的选定选项卡。在 详细信息 选项卡中的字段大部分是从正在编辑的页面上的数据预先填充的。显示标题是唯一可以更改的字段，除非是完全新的英语文章，在这种情况下，在保存之前必须填充更多字段。

存档 选项卡是进行内容编辑的地方。如果页面是翻译版本，则英语版本在左侧以只读文本区域显示。如果页面是英语版本，则编辑区域填充整个页面。编辑需要熟悉 Markdown 语法。

如果您需要查看自上次更新以来原始英语版本中发生了哪些更改，可以查看 英语差异 选项卡

源 选项卡显示了您正在工作的存档的当前源。 差异 选项卡显示了您的存档与源之间的差异。在做出任何更改之前，这将保持空状态，因为没有差异可显示。

预览 选项卡显示了您存档的 HTML 渲染效果。评论选项卡用于输入提交消息以及对任何拉取请求的反馈。

拉取请求

当存档准备好替换原始内容时，单击拉取请求按钮会使它对所有 JDM 发布者可见。该组中的任何成员都可以使用完全相同的表单检查存档。如果它是可接受的，则单击工具栏中出现的 提交 按钮（在创建拉取请求时出现），足以将更改合并到原始文章中。结果立即可见。

易用性

维护起来容易吗？答案可能是是和否。如果我自己编辑数据，只有几个可信赖的朋友，那么我想答案是是。如果有数十个或数百个贡献者在作者组中，处理所有拉取请求可能对小团队来说是一项挑战。

帮助代理

Joomla 帮助页面由代理服务器提供。URL 在您的 Joomla 安装配置文件 configuration.php 中

其中 {major} 和 {minor} 是您Joomla安装的值，{keyref} 值在管理员页面中设置以调用帮助页面，而 {langcode} 是管理员模板所使用的语言的双字母代码，例如 en 或 de。

实际上，我们不为Joomla的不同次要版本维护不同的帮助页面。并且，在从Joomla的一个主要版本迁移到下一个版本时更新帮助页面是一个重大问题。即使变化可能很小，也需要复制并重新翻译约200个原始英文页面。

使用Jdocmanual做这些要容易得多。如果您正在测试Joomla 5，您可以将配置.php文件中的域名更改为 https://jdocmanual.org/，并期望看到英文或您自己的语言的Joomla 4 和 Joomla 5帮助页面。

菜单

在Jdocmanual中，文章索引中文章项目出现的顺序与源文件列表中项目出现的顺序无关。这是通过菜单列表实现的 - 一个包含所需顺序的文章列表的文本文件。通过剪切和粘贴移动项目非常容易编辑。这比用于Joomla菜单的拖放方法容易得多。菜单顺序不受语言影响，因此每个手册只有一个菜单。用户可以创建自己的菜单副本，更改它，然后提交拉取请求以替换现有菜单。菜单仓库编辑表单具有类似于文章仓库编辑表单的选项卡。

实用工具

Jdocmanual管理员菜单中的其他项用于管理语言、翻译菜单标题和管理手册。

未来开发

Jdocmanual的开发重点在功能上。除了默认的Cassiopeia和Atum模板之外，几乎没有投入精力在外观上。欢迎提出建议和替代样式表！

编码

Jdocmanual是一个概念验证的开发项目。在底层，一些代码需要改进：处理markdown到html转换的库包含在组件本身中，而不是在Joomla库文件夹中；例如，使用Joomla GitHub库来实现git命令可能有更好的方式；等等。欢迎提出评论和建议。

内容修订

在处理和检查MediaWiki文章时，我得出结论，存在太多不必要的内部链接。在像Jdocmanual这样的良好索引中，可以省略许多链接而不影响文章的价值。这导致了更好的用户体验。到目前为止，对Jdocmanual中出现的文章的实际内容关注得很少。

我认为下一个重要的任务是更新内容，合并相似的项目，并从其他来源（如社区杂志）中融入新的内容。

结论

如果您想亲自尝试，可以在这里获取代码和数据

代码： https://github.com/ceford/j4xdemos-com-jdocmanual-v2.git

数据： https://github.com/ceford/j4xdemos-data-jdocmanual.git

请注意README.md文件。设置需要比简单安装组件更多的工作！

如果您想参与Jdocmanual代码的进一步开发，请随时提交拉取请求。