Paul Wicking

The future of documentation

Published Friday March 1st, 2019
41 Comments on The future of documentation
Posted in Documentation, Qt

“Honestly Qt’s documentation is pretty close to perfect, I wish other framework’s documentation were as good. Keep doing what you’re doing.”

“Documentation has always been top-notch”

“The documentation is great.”

These quotes are from you, the users of Qt. For someone like me, who works with documentation for a living, this is awesome. It’s extremely cool to work with docs that receive this kind of feedback from its users. In light of the sheer size of the project, it becomes even more impressive. The online documentation for Qt 5.12 spans over 18000 pages. It covers more than 3000 classes and QML types across more than 120 modules. It’s simply massive. So it probably doesn’t come as a surprise that we also get some suggestions regarding how we can improve the docs. Easier navigation, more code snippets, more examples, missing documentation (Qt3D, anyone..?) – these are all regulars. My personal favorite is perhaps not the nicest way of putting it, but it certainly does get the point across [0].

Okay, so what’s this all about, then, that makes me write a blog post about it?

The future of documentation: a workshop

Monday 11th and Tuesday 12th March, some of us that take pride in Qt’s documentation come together for a two-day workshop about documentation. The workshop takes place at The Qt Company’s offices in Oslo. We’re joined by colleagues from Finland and Germany. We’re lucky enough to have a technical writer from Luxoft join us as well, to help us understand more about what it’s like to work on Qt documentation from the outside. From developers and tech writers to product managers, we’re putting our heads together to figure out how we can improve our docs further. We want you to have more fun and get more things done.

The agenda is already on the wiki [1], along with some ideas about what we want to address. If you want to join us in this workshop, I’d be happy to welcome you aboard – get in touch with me so we can sort out the practicalities. But it doesn’t matter if you can’t join – I still want to hear from you out there. What can we do to improve the docs? Have you seen something done brilliantly in some other documentation set? (Yes, they’re brilliant, but don’t expect Qt docs to mimic IKEA assembly instructions anytime soon.) Perhaps you want to contribute to the docs, help out with some of the examples? Whatever it is, make use of the comment section to let us know about it. If you’re not a fan of the comment section, feel free to send me an email or look me up on IRC 🙂


[0] – “Your documentation examples are sometimes shitty in the sense that they cover only trivial cases, but not advanced ones.”
[1] – https://wiki.qt.io/Documentation_Workshop_2019

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

Posted in Documentation, Qt

41 comments

Jarret Gill says:

Compared to most software, I would agree that Qt’s documentation is really good, especially considering the size of it. For me the worst part of your documentation is around qmake. Whenever I try to figure out how to do something, I get directed to a page that’s actually called “Undocumented QMake” (https://wiki.qt.io/Undocumented_QMake). And even that is missing a ton of things. I usually end up finding something on stackoverflow.com where someone found something obscure in the source code that does exactly what I want, but is never mentioned in any document anywhere. (Like this: https://stackoverflow.com/a/54162789)

Paul Wicking Paul Wicking says:

I’m happy that you find Qt’s documentation (mostly) good! You’re absolutely right that the QMake documentation could be improved quite a bit. As with a number of other things, it boils down to what gets prioritized. Unfortunately, QMake doesn’t make it too high on that list. That said, we do welcome documentation patches for QMake. That could include an effort to formalize some of the content in the Undocumented QMake. Feel free to add me as a reviewer in codereview, I’m more than happy to review documentation patches!

Eli says:

I agree the documentation is very good. Bye far the most useful things are the little code snippets at the beginning of every class description which one can copy and paste and play with.

Paul Wicking Paul Wicking says:

Thanks for commenting, Eli! The code snippets are definitely there to stay 🙂

Saul says:

The pyside2 Python documentation is oftentimes a copy of the C++ docs, talking about pointers and such. It would be great to have something that is Python specific, and even better, to have docstrings to overcome the inscrutable auto-generated func(*args, **kwargs) API.

Paul Wicking Paul Wicking says:

You’re right that the Qt for Python (pyside2) documentation is from the C++ docs. As it is a wrapper for the C++ libraries, it’s sometimes impossible to get around the fact that it references C++ concepts (they’re still valid concepts even if one access them through a wrapper in a different language). The func(*args, **kwargs) style is also a consequence of using the same source for generating a new documentation set, instead of duplicating the effort that has gone into creating the C++ documentation. The main focus for the pyside2 documentation has been writing Python specific examples and getting started material.

That said, the pyside2 docs sure would benefit from more contributions. Feel free to add me to any documentation patches for pyside2 in codereview 🙂

Tres Finocchiaro says:

Best I’ve read is Java. Qt gets a close second. Worst (in my opinion) is a tie between GTK and PHP. <3

Jarret has a good point about qmake, but I think what's important to understand is that some of the "undocumented" things for other languages don't seem to exist on StackOverflow. The fact that the Qt community is willing to ask and technically able to research and answer — on an indexed, interactive medium — is extremely important for an API.

I also feel that the popularity of things like Python bindings further expands the Q&A making the knowledgebase grow faster.

Paul Wicking Paul Wicking says:

Thanks for rating the Qt docs so high! May I ask what it is that makes the Java docs better, in your opinion? In the workshop, we’re trying to uncover how we can make the Qt documentation even better, so it would be great to have a couple of concrete examples.

As for your comment regarding the community, I completely agree. The information found on the forum, SO, mailing lists, etc., way surpasses what the documentation itself could provide. In simple terms, it’s invaluable.

David N Boosalis says:

I would like to use the F1 key more in QtCreator, but the help window being integrated with the ide is a point of pain as it is never big enough to let me see all of the help, so I usually go to your on line documentation. Sure I could make the help window larger but for some reason that doesn’t work for me, as it seems to cause a fight between window space with my code window. Anyway you could add an option to put the help in it’s own window.

And for some strange reason I never use your Assistant application, as I find your online documentation layout so much cleaner and easier to navigate.

Also agree that qmake documention is my biggest source of trouble. And usually have to search the web to resovle my issues ignoring a y link that takes me to official Qt documentation on qmake. Please make your future CMake documentation first class like most of what you have

Latstly I would like to see more tooltip and “what’s this ” help integrated into QtCreators UI . So many fields and options in QtCreator that I simply do not know how to use or what they are

That’s a lot of complaining, so let me end with a big thank you for making At documentation so great and easy to use .

Paul Wicking Paul Wicking says:

First of all, thanks for your praise and for taking the time to offer some constructive criticism. I’ve made notes about your suggestions regarding the documentation experience in Qt Creator and Assistant, and I’ll pass them along during the workshop. The screen real estate feedback is particularly useful.

And yes, we want the CMake documentation to be a first class citizen! We currently have an ongoing discussion about improvements to the Qt/CMake docs here: https://bugreports.qt.io/browse/QTBUG-72159
Please do contribute if you have any suggestions 🙂

Leena Miettinen Leena Miettinen says:

The Qt Creator help should actually open in the full-screen help mode if there is not enough vertical space available next to the code editor. You can specify that the help always opens in full-screen mode or is detached to an external window. Select Tools > Options > Help > General and specify settings for displaying context-sensitive help in the On context help field. To detach the help window, select Always Show in External Window. For more information, see here:

https://doc.qt.io/qtcreator/creator-help.html#detaching-the-help-window

zhouyu5460 says:

could qt doc list pure virtual functions of C++ separately?

Paul Wicking Paul Wicking says:

Thanks for the suggestion, I’ve made a note of it for our next documentation team meeting.

Philippe says:

Documentation starts with “searching”… and in this domain, there is a tiny feature found in Visual Assist which I have become addicted to: type multiple (short) strings, separated with a space, to find symbols whose names contain all of the strings, in any order. This is very useful because it is common to not exactly remember a class or function name.

Paul Wicking Paul Wicking says:

That sounds like a very valuable tip. I’ve made a note of it, perhaps there are also other ways we could improve the documentation search. If you have other ideas, feel free to share them!

Nos says:

I can say what one of my more frustrating documentation issues was. I use Qt with Python, so the details might be different for C++ users, but using the qfiledialog class was hilariously difficult the first time I tried it. Not because the documentation was bad, but because it didn’t warn me that GUI elements had to be drawn by the main thread. I was porting code from Tk to Qt, and the tk code does an in-line file request if the default didn’t exist. Qt supplies a similar shortcut popup.
However, since it’s in a thread, this causes the entire program to crash. Took me a lot longer than I would have liked to learn the reason.
I’m sure the details are somewhere in the documentation, but it took a lucky stack exchange find for me to realize what was happening.

Paul Wicking Paul Wicking says:

With the amount of documentation we have, the details can sometimes escape the best of us 🙂

Bim says:

I agree the Qt documentation is very good compared to most other stuff out there! I do regularly hit a caveat or find a small error or a missing piece of information though that would probably help people, but see no easy way to contribute that… Maybe letting people contribute wiki-style would help there.
I also have to strongly disaggree with David Boosalis. I use Assistant, especially the index search, every day. I find the the web search results pretty annoying. You get a lot of hits you don’t want and it is much slower for me. Also Assistant shows you the documentation of the version you’re actually using.

Edward Welbourne Edward Welbourne says:

One light-weight way to contribute is to go on IRC (@ freenode.net, #qt-documentation), where someone else can turn your proof-reading notes into a patch.

Paul Wicking Paul Wicking says:

I’m happy to read that you enjoy Assistant! The web search is admittedly not brilliant, especially as includes results from multiple versions and not just the version of the docs you might be interested in.

How we can make it easier to contribute is an ongoing discussion. There have been a lot of interesting innovation in technical documentation over the last few years. Our current contribution model, through Gerrit, is sometimes an obstacle. At the same time, our rigorous review process helps maintain the high overall quality. It’s a fine line to balance!

Alex says:

I agree, I also use the index search. Alternatively, I started to use Zeal – the open source Dash-like documentation browser. Online docs are just a tad slower and don’t work on the plane.

Alexander Akulich says:

First of all, thank you for the great documentation!
I think that the next points for improvements are rather technical — it would be nice to have all code samples with highlighting and links (for classes and maybe for members) (it seems that \code snipped is not parsed in the offline docs).
I want to contribute and while I know how to improve some areas, there are still some uncovered steps in the documentation process. Especially I wonder how you get the GIFs and PNGs of the Quick items and how you generate the docs for the website (because its content is very different to the QCH help files and HTML files generated from git).

Paul Wicking Paul Wicking says:

Hi Alexander,
do I understand correctly that you would like highlighting of and links in the offline documentation? Should the links be contained in the offline docs, or link to the online documentation?

We do actually generate the online docs in mostly the same way as what you’d do offline. We apply a bit of post-processing magic, that’s all. The content should be the same, although it looks different. Regarding the look and feel of the docs on the website, there is an open issue suggesting that we include the style for offline use (see https://bugreports.qt.io/browse/QTBUG-70954).

The gifs are made using this application: https://code.qt.io/cgit/qt/qtquickcontrols2.git/tree/tests/manual/gifs
…and for the PNGs: https://code.qt.io/cgit/qt/qtquickcontrols2.git/tree/tests/auto/snippets/tst_snippets.cpp#n81

We’re also looking into other ways of making it easier to contribute and develop documentation. One idea that has been turned into a proof of concept internally, uses vagrant to build the docs, and spins up a web server to serve the content locally.

Alexander Akulich says:

Thank you, Paul! This is exactly what I wanted to get :-).

I noticed that QQC2 ToolBar as of 5.12.1 has no highlight in the QCH code snippet, but the online docs look better
https://doc.qt.io/qt-5/qml-qtquick-controls2-toolbar.html#details

I think I’ve got it — you have a list of highlighted keywords for the webversion, but both versions have no links.
On the other hand, QQC2 ToolButton uses /snippet instead of /code and the code is parsed correctly in both web and QCH versions.
https://doc.qt.io/qt-5/qml-qtquick-controls2-toolbutton.html

Probably the issue is that inline snippets in /code section have no information about language and import statements, so the doc parser has no chance to parse it as expected.

Paul Wicking Paul Wicking says:

Thanks, Alexander – I talked about this particular issue with Martin, the QDoc maintainer, this morning. We decided to push for more \snippet’s and less \code in the future 🙂

Will says:

Actual documentation for Qt 3D up to the standards of the more mature parts of Widgets would be amazing. There is an insane amount of functionality that has apparently been implemented in there. But chunks of it are basically unusable (at least in C++) for anybody who didn’t write it. Q3DFooThing is generally just documented as “Does foo for q3DThing using meta aspect invocation generator systems.” with no explanation of WTH that actually means.

AlGrenadine says:

Absolutely, Qt3d documentation needs some love

Paul Wicking Paul Wicking says:

You’re both right, the Qt3D docs need quite a bit of work. From time to time, we focus our attention on Qt3D specifically. An issue is that the API itself requires a good understanding of low-level rendering pipelines. As a consequence, writing (sometimes also reviewing) the documentation requires an even better understanding. Finally, this means that the documentation effort competes with other issues that require the same competencies. In the event that something lacks documentation entirely, sometimes we “stub out” the docs for it. That’s why you’ll find somewhat cryptic “Q3DFooThing foos thing”-type docs. It’s unfortunate, but that’s the way it is.

We’d be happy to see more documentation coming in for Qt3D, please don’t hesitate to add me as a reviewer to your patches!

Stephan says:

Building the Linux kernel is easier than building Qt. Please focus on documenting more of the build settings (skipping of modules, etc.) and it’d be great if you could invest into a build configuration tool – the kernel’s one is awesome and simple at the same time.

Paul Wicking Paul Wicking says:

The best source for build settings is currently to run ./configure –help. Your idea about a configuration tool might be a good one, why not contribute a proof of concept patch?

Asgeir says:

The API documentation is generally very good, and the system documentation can be good when I manage to find it. I really wish the system documentation had an index and a table of contents kind of thing because I have on more than one occasion found some useful bit of documentation that I then really struggled to find again later.

Paul Wicking Paul Wicking says:

Thanks for the suggestion, Asgeir! Improving the way you can find the information you want quicker is important, and one of the topics we’ll address during the workshop. Keep those ideas coming! 🙂

R Kh says:

Browsing online Qt documentation, I stumble upon missing anchors regularly. That is, some link from a documentation page includes an anchor, and that anchor is not present in the target page. IIRC, some (rare) pages even returned 404 Not Found (maybe in previous Qt versions). So it would be great if some cross-reference validator was used in an automatic manner to spot such issues early and with no human effort.

Paul Wicking Paul Wicking says:

Unfortunately, broken anchors and links happen sometimes as a result of reorganizing content, for example. We’re looking into ways of improving (or even completely avoiding) this. For now, the best I can offer is that we try to fix bugs that report such issues as fast as possible (so please, please, do report them if you come across them!).

R Kh says:

> We’re looking into ways of improving (or even completely avoiding) this
Can you please comment on the particular idea of automated validation of cross references?
Is it added to any of your TODO lists at least?

Paul Wicking Paul Wicking says:

Yesterday, we briefly discussed an approach to resolve incoming links to obsolete URLs as a result of pages that are split and/or renamed, based on manifests of the build artifacts. There was also a suggestion to re-think the standard 404-page, to provide something more helpful than what we currently have. So yes, this is on our to-do list. Until it is checked off the list, however, manual intervention is required – that’s why I request that you report broken link targets if you find them.

On a related note, the way QDoc generates links for overloads was recently changed to resolve a known issue that caused anchors to lead to nowhere. This change is already merged into 5.13.

R Kh says:

> please, please, do report them if you come across them!
This kind of work can be easily avoided by proper automation (on your side), so it is not worth doing by a human.

JKSH says:

Thanks for this initiative, Paul and team!

I added some thoughts/suggestions to the wiki page. Is that the right place to post it?

Paul Wicking Paul Wicking says:

Thanks so much for your suggestions! Especially for specific examples on how new users get stuck, that’s very useful for the on-boarding discussion 🙂

Adding ideas to the wiki is perfect, as we’ll use the wiki page to guide us through the workshop. Thanks again!

Konstantine Kozachuk says:

Thanks for good docs. Suggestions:
1) ‘This class present since Qt 5.5’ should be a link to ‘New classes and functions in Qt 5.5’. Reading release notes ‘What’s new in Qt 5.5’ often does not contain such links with full list (just overall bugs/modules etc), so I found that there are such pages only years after new Qt versions, just after thinking ‘wait, there must be such docs!’.
2) In Assistant, in Index results list, searched substring should be highlighted. Sometimes searched substring is intersection of some other useless words and highlighting can speedup this parsing process.
3) If you integrate some minimalistic code parser with highlighing, examples would look much better – with line numbers, automatically folding starting license comments etc
4) examples -> file.cpp should contain a link ‘view raw file’ and ‘view file in file system’ (if Qt downloaded such examples)
5) When I started learning Qt, QtDemo project (or how that tool was called?) was very useful – so we could quickly launch examples by categories in organized manner. New QtCreator examples tab is a mess, newcomers can be lost there.

Paul Wicking Paul Wicking says:

Hi Konstantine,

thanks for your suggestions! It’s a bit too late for the workshop, but still valuable. I have made a note of them, so that we can include it further down the road. We did discuss the welcome mode in Qt Creator and how the listing of examples is confusing to newcomers. Also, regarding your point 4, you might be interested in knowing that we’re already working on something along the same lines (see https://codereview.qt-project.org/#/c/255695/ ). I’m also very fond of your first suggestion, it seems pretty obvious that we should have something like that 🙂

Thanks again!

Commenting closed.

Get started today with Qt Download now