Paul Wicking

Update from the documentation workshop: the way forward

Published Tuesday April 2nd, 2019
15 Comments on Update from the documentation workshop: the way forward
Posted in Documentation, Qt, Uncategorized

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!

Do you like this? Share it
Share on LinkedInGoogle+Share on FacebookTweet about this on Twitter

Posted in Documentation, Qt, Uncategorized

15 comments

Richard says:

I’ve used both MarkDown and reStructuredText for writing documentation and I find the latter much better suited to comprehensive projects. The extensibility of Sphinx is a big asset that I never want to miss again. It even has a nice doxygen bridge plugin (breathe). But Sphinx/breathe requires a lot of tweaking in order to produce good-looking output that is on par with Qt’s online reference. If you could seamlessly interface Sphinx to auto-generated C++ API docs (from clang-doc?) and QML API docs and also provide a nice Qt Sphinx theme, this would be my pipe dream 😉

Markdown in turn lacks a lot of useful features and is not extensible. I’d only use it for readme files or small docs.

Fabrice Salvaire says:

I agree that reStructuredText is more suited to complex documentation and MarkDown to basic documentation.

However the internal of Sphinx can be off-putting, it is an important point if we want to customize such tool a lot. Also an extension like autodoc doesn’t work so well.

Paul Wicking Paul Wicking says:

Your point about the internals is a valid concern (although I admit I don’t know the internals of Sphinx). A driving factor in looking at what’s going on “out there” is that we want to reduce the amount of customized, home-grown tooling. Documentation is a “problem” that has been solved many times over (https://xkcd.com/927/ comes to mind). If going with a particular tool-chain requires us to customize it heavily, we might be better off not doing it in the first place. Alas, there will always be pros and cons to consider in any case.

Paul Wicking Paul Wicking says:

The Sphinx/breathe combo is interesting to study, and might prove worthwhile spending a bit of time playing around with. We’re already using Sphinx in our Qt for Python documentation tool-chain, so it goes without saying that it would be brilliant if we can use Sphinx elsewhere as well. At the same time, any change at that level risks being very disruptive in that the output (and the whole online experience) may change rather drastically – at least at first glance.

Interfacing Sphinx with output from clang-doc and styling the output for Qt is a great suggestion! 🙂 And I agree that markdown is too simple for our requirements. It is certainly good for simple documentation (as you suggest, readme files and similar), but if you require e.g. a table it comes up short rather quickly.

Richard says:

Cheers, Paul.

I’ve tried very very hard to tweak Sphinx/breathe and the ReadTheDocs theme to produce something like the Qt API referenc for a small C++ library with a bunch of classes. Similarly to Qt, I wanted to have 1 class per page. For output, I chose the popular ReadTheDocs theme. This was the blocker for me:
– It’s impossible to customize what sections are shown in which order and to what extend without hacking the breathe source code. Qt docs, for instance, creates overview sections for each class, providing an overview of all methods, enums, etc. Breathe would need a template mechanism to achieve that.
– The way breathe is designed, this would most likely require heavy architectural changes. I don’t feel elected to do that and burned out while trying to understand the 10000 factory classes in the breathe source code. I also agree that the architecture behind Sphinx can be off-putting.

Hence my suggestion of transforming an API doc database like clang’s directly into reStructuredText documents. That gives you the full power of rST and enables you to generate any page layout you like. Drawback is that you would not be able to have nice links from within code snippets to classes/methods as you can do with qdoc and doxygen. Breathe can only do that because it transforms doxygen XML (which already has links in code snippets) directly into the underlying representation of reST without using the Sphinx front-end.

For QML you would need to add a new language domain to Sphinx and implement a rST generator.

Still I find Sphinx an excellent tool for writing highly integrated and interlinked software documentation for multi-language projects, but I don’t know DITA.

Please keep us informed about your experiments and thoughts. Don’t hesitate to drop a note on the mailing list before you take any decisions. I am very interested into which direction Qt API documentation goes, because the Qt project sets a standard here.

Paul Wicking Paul Wicking says:

Thanks for taking the time to provide such comprehensive feedback, this is very helpful for us. We’ve discussed some of the same things as you point out, but you’re ahead of us in e.g. exploring Breathe. It’s great to learn a bit about your experiences!

QML is an important requirement for both current and future tooling. What would be ideal is finding a way to generate an intermediate output that includes both C++ and QML, and then piping that through a tool that spits out nice-looking docs in the other end. If that means adding a language domain to Sphinx, or if we plug in to something earlier in the tool chain, is an open question for now. Sphinx does have the advantage of being a well-supported project, and rST is a well-known format, so it is definitely in the loop.

We will of course involve the mailing list as soon as we have something a little more concrete to discuss. I hope we can move this forward a bit over the next couple of weeks, so stay tuned! And again, thanks for providing your input. That’s how we can keep setting a standard! 🙂

JKSH says:

All of this sounds very promising. I look forward to seeing the improvements!

Regarding “examples that resemble real solutions to problems” (read: large and complex) — Does it make sense to have multi-chapter tutorials which start simple but add a new module/feature per chapter? I believe this will keep the example digestible for people who are unfamiliar with the modules involved. For example, https://doc.qt.io/qt-5/qtwidgets-tutorials-notepad-example.html is extremely long and could be improved simply by breaking it up into multiple chapters.

Regarding output format — I see that DITA Open Toolkit provides multiple formats, including HTML and Markdown. If you need an even more powerful/versatile HTML output, a possible approach is to generate Markdown and use a dedicated HTML generator (like https://jekyllrb.com/ ) to do the layout, styling, etc.

Paul Wicking Paul Wicking says:

I’m happy to hear you’re looking forward to the improvements, JKSH! 🙂
You hit the nail on the head: the idea of large and complex examples involves multi-chapter tutorial style content. One idea we discussed during the workshop involved developing these examples based on the syllabus for the Qt certification exams. Another idea involved a git repository with branches that show the state of the code “per level”, so to say. These are not mutually exclusive, of course.

There are a lot of opinions on how this can and should be done, and I am a firm believer in having a clear target for what our training material is expected to teach the user. How can we improve on something if we don’t know what the result is supposed to be? Defining the requirements isn’t easy, however, and this is a part of the reason why these “personas” are important.

When it comes to output formats, HTML is a given requirement. Today, QDoc creates the bulk of it, and then we have some post-processing scripts that chew their way through it and turn it into what you see on the documentation site. For future tooling, we can hopefully get to a state where content and presentation is completely separate.

beeka says:

Sounds like a productive workshop. Searching for DocWorkshop03.19 text does not show the issues, and I can’t find a way to search by label, so I can’t comment on the issues directly.

Regarding the examples: there is a overwhelming number of them from the welcome/examples page. However I would be wary of pruning them too much… perhaps they need grouping more than deleting. I am often looking for either something I can compile / experiment with to better understand a specific API (e.g. Image Composition Example) or a more general tutorial-style example (e.g. Qt Quick calculator). It might be useful if there was a way to create / link to a project that contains the code in the API docs (and compiles).

Side note: I used .ui files almost exclusively and have to engage brain to ignore the basic UI setup stuff. Ideally, for me, .ui files would be used in the examples so that the code is focused on the point being demonstrated.

I’d be interested to see what you make of DITA. I looked at using it for creating user documentation along side technical support docs. The output formats from DITA-OT are impressive but the input support was limited. When I looked you could only generate from MS-Word topics: they now support markdown, which helps with version control but makes managing images trickier. The difficult part was managing the topic map: this is more detailed than I was expecting and benefited from (commercial) tool support. My vision of developers including user documentation with the code for their new feature and the CI generating a beautiful set of multi-level documents never materialised.

Paul Wicking Paul Wicking says:

Hi beeka, thanks for your feedback! I’ve updated the post to include a link to a query on Jira that lists all the issues, I hope that helps.

Regarding the examples, we are _not_ going to delete them all. But as you correctly point out, the sheer amount of examples on the landing page is overwhelming. One of the reasons we want to collect them in a git repository, is that it would (hopefully) make it easier to check out the source for a specific example and compile it. As such, these examples might not have the strictest requirements in terms of amount of accompanying text or comments. They could be self-documenting in terms of neatly written code, and when it comes to understanding the API, sometimes it is better to step through the example with a debugger than to read some more or less descriptive comments. The tutorials on the documentation site should, however, be fairly comprehensive and exhaustive. The idea is that they should aim at teaching you what you need to know to be able to make use of all the other examples and API docs we have. Your request for more .ui-files is noted 😉

DITA is pretty daunting and it comes with capabilities and limitations. What we have discussed so far involves hiding the DITA specifics from the content creation, in terms of not littering our source files with a bunch of DITA syntax and requiring developers to learn how to write within it. We want to make it easy to contribute documentation, and easy to develop documentation alongside code. If we can manage to place this within a framework (such as DITA, but perhaps something else) that allow us to control the structure of the output as well, we believe we can decouple things in such a way that it facilitates rapid documentation development.

This is all very much in the early stages as of yet, so I appreciate your comments and suggestions a lot. I’m not entirely sure if I’m convinced that DITA is right for us, but I still feel confident that it is surely worth looking into. Learning more about your experiences with both DITA and other formats is extremely valuable!

beeka says:

Thanks for the quick reply. If you do go the git-route for examples, it would be useful to be able to download them all as a bundle (and plug into Qt Creator / Help?) as at work our development environment does not have internet access. While at home I don’t have git on my Windows machine: installing it just for an example will feel like a high barrier. I find compiling the examples now quite simple, once I find the example.

DITA sounds like a useful idea: you could generate documentation with Qt contributor / design notes or simpler user API docs… but I was only given a few friday afternoons to look into it. I was probably after something less powerful than the DITA topic maps, e.g. a c-preprocessor.

Paul Wicking Paul Wicking says:

Pointing out that git isn’t necessarily available all over is a valid concern. This can partly be mitigated by offering zipped downloads as well, can’t it? I’m thinking along the lines of how you would browse and access source through the github/gitlab webUI.

The integration with Qt Creator is also important! I believe we need to improve the experience of Creator’s “Welcome” mode, which is supported by a lot of the feedback we get. Currently it is pretty much throwing everything we have at the user, and that can make it difficult to navigate and find relevant content. Even this requires quite a bit of manual maintenance between different releases. So we’re definitely paying attention to this when we’re trying to come up with new ways handling this.

And yes, structured authoring (DITA being one such framework) is definitely useful given the scope of our needs, and totally overkill in smaller documentation projects 🙂

d3fault says:

If you do move all the existing examples to a separate repo, I urge you to have the Qt SDK install that repo by default. And since I doubt you’re going to rewrite git history, moving them to a new repo won’t really accomplish very much in the first place.

I disagree that the examples should “use the broad spectrum of Qt”. I prefer the examples I’m reading to cover a single very specific concept. The redundant code (necessary for compilation) is warranted and easily skipped. Code “snippets” belong in Tutorials. What you’re describing, projects that “use the broad spectrum of Qt”, would imo be categorized as “Demos”, not “Examples”.

Paul Wicking Paul Wicking says:

One of the main reasons for gathering the examples in a common repository is dependency management. With the current structure, the examples may end up imposing otherwise unnecessary dependencies on a module as a whole (which is a bit silly). An even stronger argument is that modules may end up depending on each other. As an example, you can’t use Controls2 in Qt Declarative, which means we keep reinventing the button. In other words, this practice effectively blocks multi-module examples as an unwanted side-effect, and having examples live in a repository for examples seemed a reasonable approach to solve this. And if in the end they are labeled tutorials, demos, or examples, we still need to be able to show an integrated approach to solving real world problems.

What you suggest about having the installer install this by default is an important observation. Thanks for pointing this out! If we come to doing this, I think it makes sense to have it as a selectable option (which can of course be on by default). As I understand, there is currently an effort underway to improve the installer, so I guess it depends partly on how that ends up.

lewis machilika says:

i am failing to install qt5.9 but i wanted to use advanced features of qt. so in that case i wanted to use online qt. help me how can i use that

Commenting closed.

Get started today with Qt Download now