本文翻译自Update from the documentation workshop: the way forward 原文作者：Paul Wicking 这篇博文是对我们3月11-12日的文档研讨会的总结。此次研讨会举办地点是Qt公司在挪威奥斯陆办公室，参会者除了Qt产品经理、软件工程师、研发经理和文档工程师，还有我们合作伙伴Luxoft的文档工程师。研讨会前一周，我发了一篇博文预告，并收到了很多反馈（感谢大家！），这些评论和邮件回复我都一一记录在案。所以，尽管您未能到场，但您的想法都在！

到如今，我们已经在Jira中添加了一堆占位任务，并将在接下来的三至六个月内开展这些任务。接下来，我将阐述本次研讨会上的几个亮点，这或许会让Jira中的任务列表更有意义。同时，也欢迎您参与对这些议题的评论与投票！ 译者注：

• 如您对某项任务特别感兴趣，请前往原文，直接评论并对这些问题进行投票！
• 来自这次研讨会的所有任务项请参考

为什么要文档化？

我们设定了六个“角色”，作为进一步讨论的基础。这些角色旨在帮助我们与目标受众（也就是您）建立联系并指导Qt今后的文档工作。我们将进一步细化这些角色，并希望能在未来博文中有条理地一一阐述。现在，它们还只是写在一堆报事贴上的关键字，贴在我办公室的窗口上。 我们还就提供文档的动机进行了更高层次的讨论。您的回复为我们的讨论提供了框架，以下是我们确定的部分问题领域：

• 文档登录页面的结构很差，特别对于新用户来说，难以确定从哪里开始或下一步去哪里。
• 文档信息太密集。需要进一步细化标题。
• 需要更多的概述文档和概念文档，以及连贯的文档组织方式，能轻松找到彼此相关的主题。
• 需要更多最佳实践文档，并解释为什么要采用某种方式。
• 大量例子没必要，其中一些很难为初级到中级用户消化。
• 在类/概述文档中，示例通常只显示很少部分，以片段展示会更好。
• 维护很困难，尤其是示例。有些可以追溯到很多年前，个别甚至有十年以上历史。
• 基本要求/先决条件未归入官方文档，例如，那些在wiki.qt.io上的构建依赖项，这会在其他地方（例如，各种论坛）产生争论。

工具

首先，关于工具的讨论是关于当前QDoc工具实现的技术讨论。我们就今后工具文档的要求进行了更高层次的讨论。目前，QDoc使用编译器Clang来解析C ++，使用QML解析QML。从开发的角度来看，目前的重点是清理QDoc代码库。 Qt开发者在文档方面的难点是构建文档的复杂性，这使得在开发代码的同时写文档非常困难。随着时间的推移，会变得越来越复杂。目前，我们要求所有相互引用的模块都配备QDoc的.index -files。这意味着您必须至少在整个代码库中运行make prepare_docs一次。我们在研讨会上达成的共识是，每个翻译单元的增量文档构建将优于当前的工作流程。

QML和跨平台考量

解析QML是未来任何工具的硬性要求。此外，我们还要求完整文档集包含跨平台内容。我们可以通过先生成结构化的中间输出来实现，构建最终输出的工具可以使用它。这样就可以使内容不依赖于呈现形式（HTML、PDF等）。选择拆分内容和展示形式也可能会影响我们创建概述和主题文档的方式。建议将DITA和DITA Open Toolkit作为潜在的整体结构。AsciiDoc、DocBook和reStructuredText是可选项。Qt公司的文档团队将研究各种方法的功能和局限性。 另一个需要考虑的问题是PySide2对于如何生成文档也有关联需求。远离当前的QDoc 和proprietary webxml输出意味着PySide构建工具也需要重新设计（但其本身可能就有改进）。

其他方法

我们还讨论了文档工具的现状。较新的语言，如Go、Python和Rust，已将文档编写作为其功能特性之一。如果C++将文档编写作为一种语言特性，编译器会支持它。这将有利于整个C++社区，而不仅仅是Qt项目。

未来的努力方向

我们要优先考虑的两个领域是示例和工具。许多示例都很小，并且不包含多个模块。拆除这些“筒仓”并提供类似问题真正解决方案的示例可能会更好。一个建议是将我们当前的大量示例转移到一个单独的存储库。然后我们可以创建一系列应用广泛的Qt应用程序示例。除了系列教程，这些示例旨在教授足够多的Qt知识，并且能够让用户在创建自己的应用程序时使用API文档。 至于工具，我们想通过一些新的举措来探索更多可能性。我们也已经致力于此。毕竟，我们在写C++代码方面确实有一些经验。一个让我们兴奋不已的项目是clang-doc，我们将进一步了解并寻找类似的方式。 最后，我们同意文档应作为正常构建的一部分，在CI环境中构建。文档质量应该是CI控制的一部分。例如，可以阻止增加来自QDoc警告数量的补丁。 当然，一篇博文无法完整总结我们两天的讨论，但希望本文传达了一些我们有趣的想法，Jira上的任务表明我们致力于改进Qt文档体验。当然，我们很乐意听到大家的反馈，您可以在IRC上查找我们团队，或者最好能与我们所有人在bugreports.qt.io讨论！