What kind of overviews do you miss in the Qt documentation?

kkoehne

Hi, after Hanna had such a good discussion with her question on how to learn Qt, I figured I want to tab in your collective knowledge, too :)

Qt is generally praised for it's good reference documentation (though I definitely also see improvement ideas there)! But in our last customer survey, some people were raising that particularly the overview documentation is lacking.

And no doubt, there are things to improve. We have a wealth of information in the Qt 6 Overviews, but of varying quality. I'm actually going through many of the pages myself to collect pages that need an update.

Anyhow, finding outdated information is arguably the easy part. The more interesting question to me is: What are we missing? What is the topic in Qt you have been struggling with - or you see others often struggling) - where a concise overview page would help?

Thanks in advance for your feedback!

JoeCFD

Qt examples are too small. Add some open source projects made with Qt and explain them step by step in details.

kkoehne

@JoeCFD, thanks for the feedback. Having examples that also show architecture & good coding practices is indeed something raised often. Anyhow, the challenge is to make the examples still simple enough, so that you're not overburdened with the details of a real world app.

Do you have a specific open source project or use case in mind that would make up a good example?

JonB

@kkoehne said in What kind of overviews do you miss in the Qt documentation?:

Anyhow, the challenge is to make the examples still simple enough, so that you're not overburdened with the details of a real world app.

I agree. In any case, how would Qt documentation keep up with any open source project's updates?

SimonSchroeder

Two things come to mind right out of the top of my head (though I haven't checked the overviews in detail).

One of the most common things I've recently commented on in this forum is the use of threads. I'd very much like to see it in the section "Best practices" (might just link to QThread's documentation directly). I am not sure how well the current documentation of QThread represents current best practices. Usually, https://mayaposch.wordpress.com/2011/11/01/how-to-really-truly-use-qthreads-the-full-explanation/ is/was? the go-to place for information how to use QThreads properly. The Qt documentation on QThread might have changed in the meantime (I don't know). One way to quickly fire off new threads is using lambdas (with either QThread::create(...)->start() or QtConcurrent::run(...)). The main problem here is how to report back progress to the GUI (think QProgressDialog). I personally don't see why you should reimplement QThread and have a signal to connect with the progress dialog. My solution to this problem can be found here: https://github.com/SimonSchroeder/QtThreadHelper . I think that QMetaObject::invokeMethod on the GUI thread is a reasonable solution to advance the progress dialog. (Probably, there's also a "Best practices" for progress dialogs in general missing: If you update the progress dialog on every iteration of the loop it might slow everything down if it happens too often. I now use QTime::elapsed() to decide when to update the progress dialog. And calling QApplication::processEvents() is certainly one of the worst solutions to progress dialogs (though often the easiest one).)
I've seen a "Scalability" section under "Best Practices" (linking to "High DPI"). A lot of it pertains to QML. We are using QtWidgets instead. Maybe I haven't found the proper solution, yet. Here is my problem with scaling: I have two monitors, one 4K and one 1080p with (almost) the same physical size). Obviously, the pixel ratio is different for the two screens. We have special code to treat changes in scaling when moving the window from one screen to the other, updating the pixel ratio, tool bars, etc. Maybe the problem is specific to our approach (an Qt 5): our icons are SVGs and need to be rendered for the toolbars. They are re-rendered in the proper resolution when the pixel ratio changes. Also, we have some self-drawn buttons that need to adapt in size. Has this improved with Qt 6? Otherwise I would very much like to see the topic of two different pixel ratios handled in the documentation (happens quite often when people plug in a monitor into their laptop). Would be much better if Qt would do it automatically.

J.Hilk

@kkoehne what in my opinion is lagging is

a) a proper search engine :D I find myself using the google search, with restriction to the documentation rather, than browse/search through it myself e.g site:https://doc.qt.io QWidget

b) the bug, that the table of content is simple missing, if your browser is to small, is terrible!

Missing:

There:

Same that the table of content is not scrollable, you have to scroll to the end of the page for the table to be able to scroll

c) A proper overview of all Qt Classes and Modules that exists. I often enough stumble over classes I had no idea existed :D

SimonSchroeder

@J-Hilk said in What kind of overviews do you miss in the Qt documentation?:

@kkoehne what in my opinion is lagging is
a) a proper search engine :D I find myself using the google search

I use the search integrated into QtCreator. Using the index is quite good (though it is terrible when you have multiple versions of Qt installed, because then you need to choose the version every time; you used to be able to select just a single version, but this option does not work well anymore because you have to choose which module (QtCore, QtWidgets, ...) to search in; (just tried it again, and it seems that not even this option is there anymore; and in the dialog I don't see anymore which version I am selected (unless I hover...))). I normally just select any of the versions and then this search option is quite "good".

@J-Hilk said in What kind of overviews do you miss in the Qt documentation?:

c) A proper overview of all Qt Classes and Modules that exists. I often enough stumble over classes I had no idea existed :D

There's this for modules: https://doc.qt.io/qt.html
And also (though per module) an overview of the classes, e.g. for Qt Core: https://doc.qt.io/qt-6/qtcore-module.html

Or do you have something different in mind?

J.Hilk

@SimonSchroeder said in What kind of overviews do you miss in the Qt documentation?:

Or do you have something different in mind?

Actually I had different grouping in mind, something like:

"Persistent Storage/Memory"

QFile
QFileSystemWatcher
QSettings
.... etc

And I wasn't really aware of the general classes in module overview! How do you navigate there from QtCore, if you don't know it exists?

SimonSchroeder

@J-Hilk said in What kind of overviews do you miss in the Qt documentation?:

And I wasn't really aware of the general classes in module overview! How do you navigate there from QtCore, if you don't know it exists?

I googled "Qt documentation". It first asked if I wanted Qt 5 or Qt 6. Clicking on "Qt 6" immediately gave the module overview. On the Qt Core module webpage there is a section "Reference" with "C++ classes" as its first link.

I just figured out one more: On the left there is also "Reference" in the menu. And this has a link "All C++ classes" when expanding. This gives you: https://doc.qt.io/qt-6/classes.html . Not sure if that is actually helpful for a beginner. At the top of the all classes webpage there is a link to "All classes by Module": https://doc.qt.io/qt-6/modules-cpp.html . Though this is both not the way you describe it.

Still, I would say it is quite easy to navigate if you are new to the online Qt documentation.

kkoehne

Hi Simon! Thanks for your input! Some comments:

@SimonSchroeder said in What kind of overviews do you miss in the Qt documentation?:

One of the most common things I've recently commented on in this forum is the use of threads. I'd very much like to see it in the section "Best practices" (might just link to QThread's documentation directly). I am not sure how well the current documentation of QThread represents current best practices.

There's a long standing bikeshedding discussion on how to 'properly' use QThreads :) The latest QThread documentation IMO does however give a somewhat balanced view: It first introduces the 'Worker/Controller' pattern, where QThread is a member of the controller. Next, it shows how to subclass QThread (the original pattern that has it's issues, but is also very compressed). What's arguably missing in the overview is QThread::create(...) ...

One way to quickly fire off new threads is using lambdas [...] The main problem here is how to report back progress to the GUI. [...] My solution to this problem can be found here: https://github.com/SimonSchroeder/QtThreadHelper .

I like it actually! Have you considered trying to upstream it?

I've seen a "Scalability" section under "Best Practices" (linking to "High DPI"). A lot of it pertains to QML. We are using QtWidgets instead.

Good point! Added https://bugreports.qt.io/browse/QTBUG-104236 to track this

Here is my problem with scaling [...]

I know that there's been continous work on the issue of high dpi, but I'm not aware of the details :/

kkoehne

Thanks J-Hilk for your input!

@J-Hilk said in What kind of overviews do you miss in the Qt documentation?:

a) a proper search engine :D I find myself using the google search, with restriction to the documentation rather, than browse/search through it myself e.g site:https://doc.qt.io QWidget

We're actually using google for the search box on doc.qt.io too, so your experience shouldn't really differ ;)

That said, we recently noticed a bug where google was not indexing all pages anymore due to the sheer size. Anyhow, we have solved this now by explicitly de-listing pages in the archive. We furthermore now marked the Qt 6 documentation as 'canonical', and added a selection box for you to easily go to other supported versions.

All inall, the search results should now give better results, be it from google.com or from the search box.

b) the bug, that the table of content is simple missing, if your browser is to small, is terrible!

Well ... that's a feature to show enough content also on smaller screens. When the width is too low, we first hide the right toc, and then the left toc, to make sure there is sufficient space for the actual content (middle column). What we could do maybe is tweak the exact points where this happens, but in general, I think it makes sense and is fairly standard (check out e.g. the microsoft API documentation). Or we somehow merge the global TOC, and the site-specific TOC to the left side. But I'm not sure this would be an improvement overall.

kkoehne

@J-Hilk said in What kind of overviews do you miss in the Qt documentation?:

Actually I had different grouping in mind, something like:
"Persistent Storage/Memory"

QFile
QFileSystemWatcher
QSettings
.... etc

Maybe something like https://doc.qt.io/qt-6/io.html ? Granted, it is a bit hard to find currently, you have to go to "All Qt Reference Documentation", "Groups Of Related Classes" ...

How about adding a a 'back-link' e.g. to the respective class documentation ?

JoeCFD

@kkoehne Qt Creator can be one of them.

Kent-Dorfman

I miss the days of the Trolltek docs...you know, before it was redone in low contrast style sheets. After about 2007 most web interfaces just look like white noise and/or clutter to me.

Kent-Dorfman

FWIW, do not pin these posts...it's annoying.

JonB

@Kent-Dorfman said in What kind of overviews do you miss in the Qt documentation?:

After about 2007 most web interfaces just look like white noise and/or clutter to me.

So much for the Internet then... ;-)

kkoehne

@JoeCFD said in What kind of overviews do you miss in the Qt documentation?:

@kkoehne Qt Creator can be one of them.

Hi JoeCFD, can you explain a bit? I'm not actually sure what sub-discussion you're replying to ...

kkoehne

@Kent-Dorfman said in What kind of overviews do you miss in the Qt documentation?:

miss the days of the Trolltek docs...you know, before it was redone in low contrast style sheets. After about 2007 most web interfaces just look like white noise and/or clutter to me.

If the documentation is to bright for you, doc.qt.io features a dark mode since a while ...

https://www.qt.io/blog/dark-theme-for-qt-online-documentation

JoeCFD

@kkoehne Do you have a specific open source project or use case in mind that would make up a good example?
You guys can make Qt Creator source code as an example.

Toryrutter

Qt samples are not large enough. Include a few Qt-based open source applications and provide detailed step-by-step instructions.