Update from the documentation workshop: the way forward

This is an update from the documentation workshop we had 11th and 12th March. The location was The Qt Company's location in Oslo, Norway. The participants were product management, software engineers, and R&D managers from TQtC. We also had documentation engineers from both TQtC and Luxoft. A good week before the workshop, I blogged about it. The blog post received tremendous response (thanks!), and I brought my notes from your comments and emails. So although you weren't physically in the room, your ideas definitely were!

Since then, we've added a bunch of placeholder tasks in Jira. We will expand upon these as we go over the next 3-6 months. In the following, I would like to describe some of the highlights from the workshop. Perhaps it will make the Jira tasks make more sense. Also, please comment on and vote on these issues in!

(Tip: I labeled all the issues DocWorkshop03.19, so they should be easy to find. Edit: This link takes you straight to the search results.)

Why documentation?

We came up with six "personas" to serve as a way to anchor the further discussions. These personas were meant to help us relate to the target audience (i.e. you). The idea is to let these guide our future documentation efforts. We will develop these personas further, and I hope we can present them in a coherent manner in a future blog post. For now, they are a bunch of keywords on post-its on my office window.

We also had a higher-level discussion about the motivation for providing documentation. This discussion was framed by the response we got from you. Some of the problem areas we have identified are:

• The structure of the documentation landing pages is poor. This makes it hard, in particular for new users, to figure out where to start or where to go next.
• The documentation is very information dense. Further separation of topics is beneficial.
• We need more overview documentation and conceptual docs, with coherent organization. It is unnecessarily hard to find topics that relate to each other.
• We need more best-practice documentation, and explanations of why we do things in a certain way.
• The sheer number of examples is daunting, and some of them are hard to digest for beginner to intermediate level users.
• Examples commonly show only minor bits that may serve better as snippets in the class/overview documentation.
• Maintenance is difficult, in particular of examples. Several go back many years, some even more than a decade.
• Basic requirements/prerequisites are not part of the official documentation. This includes build dependencies (these are on wiki.qt.io). This generates "noise" elsewhere, such as on the forums.

Tooling

At first, the discussion about tooling was a technical discussion about the current QDoc implementation. Then we had a higher level discussion regarding the documentation tooling requirements of the future. Currently, QDoc employs Clang to parse C++, and the QML parser for QML. From a development perspective, the current focus is to clean up the QDoc code base.

A pain point for Qt developers (when it comes to documentation) is the complexity of building docs. This makes it difficult to develop docs alongside code. This has become increasingly complex with time. Currently, we require all modules that reference each other to have QDoc's .index-files. This means you have to run make prepare_docs across the entire code base at least once. The consensus in the workshop was that incremental documentation builds per translation unit would be preferable to today's workflow.

QML and cross-platform considerations

Parsing QML is a hard requirement for any future tooling. Also, we require cross-platform content in the complete documentation set. We can achieve this by first generating a structured intermediate output. The tool that builds the final output can use this. This could then be independent of presentation format (HTML, PDF, etc). Choosing to split content and presentation may also impact how we create overview and topic documentation. DITA with DITA Open Toolkit was suggested as a potential overall structure. AsciiDoc, DocBook and reStructuredText are alternatives. The documentation team at the Qt Company will research the capabilities and limitations of various approaches.

Another point of consideration is that PySide2 has also requirements that relate to how we generate the documentation. Moving away from the current QDoc/proprietary webxml output means that also PySide build tools need a redesign (but that might be an improvement in itself, of course).

Other approaches

We also discussed the state of documentation tooling. Newer languages, such as Go, Python, and Rust, provide documentation as a feature of the language itself. If C++ had documentation as a language feature, it would be supported by the compilers. This would benefit the C++ community at large, not just the Qt project.

The way forward

The two areas we want to prioritize are examples and tooling. A lot of the examples are small, and they do not include multiple modules. It would probably be better to tear down these "silos" and have examples that resemble real solutions to problems. One suggestion is to move our current slew of examples to a separate repository. Then we can create a set of example applications that use the broad spectrum of Qt. Along with a tutorial series, these examples can aim at teaching enough about Qt to let users use the API documentation when creating their own applications.

When it comes to tooling, we want to explore new initiatives out there to learn more about the possibilities. We might also have something to contribute. After all, we do have some experience in documenting C++ code already. A project we found exciting is clang-doc, and we will explore this and similar approaches.

Finally, we agreed that the documentation should be built in CI as part of normal builds. Documentation quality should be part of CI gating. For instance, patches that increase the number of warnings from QDoc could be blocked.

Of course, summarizing the entirety of two full days is way out of scope for a blog post. I hope I've managed to convey some of the interesting ideas that were discussed, and that the tasks in Jira show that we're committed to improving the Qt documentation experience. I would love to hear back from you out there, though. Use the comments, send me emails, look the team up on IRC, or (even better!) engage with us all on bugreports.qt.io!