What happened to the glorious Qt documentation?
-
Just returning to Qt after about 5 years away from it. One of the most positive things I remember about it was the quality of the documentation. Everything was well documented and easy to find.
Fast forward to 2013 and me having spent a few days setting up a Qt project and navigating the Documentation pages. I am sorely missing some kind of index or overall structure or even a sitemap. I seem to find important pages only by randomly clicking through links embedded inside text inside other pages.
For example, just now I was reading http://qt-project.org/doc/qt-5/thread-basics.html, and then by chance through Google also found another page with the same name, also for Qt5 but with more information:
http://qt-project.org/doc/qt-5.0/qtcore/thread-basics.html
I've now started my own personal little Qt Docs HTML link page just to be able to find stuff again. :)
-
Qt Project web page maintains several Qt version documentations in parallel. So, if you want the newest stuff, make sure there is "5.1" in your URL (and soon it will be 5.2).
If you want everything to be consistent and most up-to-date, install Qt on your system and use Qt Assistant, or Qt Creator's Help.
-
Unfortunately, the handling of the documentation webpage gets even worse than before.
Since introduction of Qt5.0 or maybe Qt5.1 the search behavior was not optimal anymore. Searches brought up google search return all the time. Searches within a particular version as it was meant initially were close to impossible.Since a couple of days the search box is gone completely. This renders the whole document on the webpage apparently useless. At least it is not intuitive to use at all.
[quote author="sierdzio" date="1386943367"]
If you want everything to be consistent and most up-to-date, install Qt on your system and use Qt Assistant, or Qt Creator's Help.[/quote]I have to get used to Assistant which will probably work for my own use.
However, this forum will suffer ultimately from this change. The more effort required for finding an URL to relate to documentation on the web, the less people will be willing to invest time in doing so. -
You are right, since Qt 5 was released the overall experience on this web page has degraded a lot. Links to class names in code snippets still don't work as they used to, Qt 5.1 is not officially available in search results (I usually open Qt 5.0 docs and then manually change the url to 5.1). Plus, there are documentation snapshots which increase the confusion.
For searching, I have not seen any change recently - I am always using the global search box (top-right of the page) and then narrow it down by clicking on "Qt 5.0 documentation".
All this, of course, has nothing to do with Qt documentation as such (it's as great as it's used to be, and is constantly being improved), it's just the interface here on qt-project.org. There used to be plans to improve the matter, Knut has organised lots of meetings over IRC to resolve the issues, but then it abruptly stopped and the code seems to be bit-rotting since.
-
For searching, Google has a "site:" operator that lets you filter by URL. So, I've been searching this way from my browser's search bar:
@
site:qt-project.org/doc/qt-5.1/ threads
@(I made an extension to Google Chrome to add the prefix with a keyboard shortcut)
Qt 5.2 started using canonized URLs to improve search results over time (https://bugreports.qt-project.org/browse/QTBUG-32580 ) so the docs are now at www.qt-project.org/doc/qt-5/ Unfortunately, Google's algorithms see "site:qt-project.org/doc/qt-5/" and return results for qt-5.1 and qt-5.0 too. :(
[quote]For example, just now I was reading http://qt-project.org/doc/qt-5/thread-basics.html, and then by chance through Google also found another page with the same name, also for Qt5 but with more information:
http://qt-project.org/doc/qt-5.0/qtcore/thread-basics.html[/quote]Be careful not to confuse "more text" with "better information". This particular page is shorter in the Qt 5.2 because:
Before, there was lots of duplicated material before, yet each copy was incomplete. They have now been merged into relevant sections/pages. Many paragraphs in the Thread Basics page have been replaced with links to those topical pages.
The examples at the bottom were removed, because they were duplicated (Examples 1 & 2 -- follow the replacement links instead), unnecessarily long-winded (Example 4 -- see the QThread page instead), or downright bad (Example 3).
P.S. If you're interested in reading about threads, the overview is at http://qt-project.org/doc/qt-5/threads.html
-
[quote author="JKSH" date="1386950044"] Before, there was lots of duplicated material before [/quote]
Hehe, sorry for pointing that out, I just can't stop myself :D
-
Haha! Er... I was merely illustrating my point with a mere illustration ;)
-
At least with Qt 4.x documentation there was a functionality in the right panel allowing to search for specific classes.
At top in the right panel there has been and there still is the tag field. This has been confused with a class search for long and added a lot of stupid tags to the initial page. I think in the past Alexandra had to clean up once in a while.
However, further down was a lineedit where you could start to type the class and it brought up fast different choices. The actual version was selectable through a combobox. The functionality was still there about a week ago, but the return was a more general google search on devnet. You had to be careful to pick something from the correct version. Unfortunately the newest versions were not always on first page.
Now even this is gone.
There is an extension from Volker to Chrome. it was not happy about the transition to Qt5 either, but somewhat usable. It did not work anymore properly in the last week.@JKSH Is your extension of chrome available somewhere?
-
Agreed too, I wonder what can be done to make the situation better ? Is it a publication problem ? The new documentation format that causes trouble online ?
-
It might be more an issue of the Nokia->Digia transition aftermath. Too many changes in responsibilities for devnet.
I wonder if there is somebody really responsible at all at the moment. Only occasionally that you see someone from Digia posting and if they do, they seem to do on own initiative. -
[quote author="JKSH" date="1386950044"]...the docs are now at www.qt-project.org/doc/qt-5/ Unfortunately, Google's algorithms see "site:qt-project.org/doc/qt-5/" and return results for qt-5.1 and qt-5.0 too. :(
[/quote]Found a workaround! Just need to explicitly tell Google to exclude qt-5.1 and qt-5.0. That's a pain to do by hand though.[quote author="koahnig" date="1386952677"]At top in the right panel there has been and there still is the tag field. This has been confused with a class search for long and added a lot of stupid tags to the initial page. I think in the past Alexandra had to clean up once in a while. [/quote]So THAT'S why strage tags keep appearing on the index page! I've cleaned up that page a few times, thinking that it was the work of some trigger-happy tagger.
[quote author="koahnig" date="1386952677"]There is an extension from Volker to Chrome. it was not happy about the transition to Qt5 either, but somewhat usable. It did not work anymore properly in the last week.
@JKSH Is your extension of chrome available somewhere? [/quote][quote author="Andre" date="1386959849"]Fortunately, you can still access the docs offline as well, and the search there works great. It only misses the doc notes...[/quote]I found Volker's extension and tried it out. It looks like it can start working properly again if the qt-project.org API implementation was brought in line with the Qt 5.x released.
I polished mine and published it at https://chrome.google.com/webstore/detail/qt-doc-search/gfigdpnkjnilcielpnmfmdnnbloabjoh/ (I'll announce it the the rest of the forum later). It uses Google Web Search instead of the Qt Project API. It focuses on version-specific searching of the documentation, and can find doc notes if the notes were published for the selected version. It doesn't look for videos/FAQs/etc. however.
-
Thanks for information on your extension.
I gave it a shot and it is helpful. Apparently, one should switch off Volker's extension first. At least it did not work right away and after switching off Volker's it worked.
The only I have noticed is that the auto-completion is not working, but that is clear, that was coming from the possible API access.Anyway, very nice job!!!
In my opinion already worth to announce to all.
-
Interesting and very useful indeed !
Any chance of a safari version (or maybe a possibility to contribute to it) ? Could be handy when using a VM :)
-
Thanks guys; I'm glad you find it useful :)
@SGaist: No plans for a Safari version, but I've released the source code (it's very small). Details at the "official announcement":http://qt-project.org/forums/viewthread/36199/.
