Harmonizing the Qt 5.x Documentation

jpasion

Hello all,

Short summary: We will be redirecting viewers of Qt 5.0 and Qt 5.1 documentation
to "Qt 5" documentation. Subsequently, we will remove the 5.0 and 5.1 documentation
from qt-project.org and we will place future Qt 5.x documentation in
"Qt 5" (http://qt-project.org/doc/qt-5/).

Note that the Qt 4.7, Qt 4.8, and Qt Creator Manual are not part of this change.

Why are we doing this?

Because, overall, it is easier to move the documentation as-a-product forward.
But to be specific:

A)When Qt 5.0 was released, much of the documentation such as pages and snippets
were missing and were fixed for the Qt 5.1 release. People looking into the Qt 5
documentation will likely encounter the 5.0 version. Harmonizing the directories
into one means that online viewers will always view the latest Qt 5 documentation.

B)Multiple directories hinders the search results. A single directory for Qt 5
documentation increases traffic to the /doc/qt-5/ directory. Currently,
the /doc/qt-5.1 and /doc/qt-5.0 directories are taking away viewers from the
main Qt 5 content.

Some Practicalities:

-We need to be stricter with filename changes to minimize readers viewing non-existing pages.
The Qt Writing Guidelines and QDoc already dictate the filenames for important
pages, but overview and article authors should minimize filename changes.

-It is even more important to make sure that the API has the correct QDoc commands
and markup. API should have the \since and once needed, the \deprecated, and
\obsolete commands.

-I checked the doc notes database and there are only a handful of doc notes
for both 5.0 and 5.1. It is likely that they will not be ported over.

-The 5.0 and 5.1 HTML files will be hosted in doc.qt.digia.com. Regardless,
they will always be available when downloading the packages.

The exact timeline is not decided yet, but the redirects are being tested
internally now and we hope to deploy them before the Qt 5.3 final release.

Cheers,
Jerome P.
Documentation Engineer - Digia, Qt

SGaist

Hi,

For the current doc notes available, you could contact the authors to ask them to port the notes, so they would not be lost if they are providing useful information.

Anyway, thanks for the cleanup !

Cheers

jpasion

Hello,

Thanks for the idea. I will do that.

Cheers.

JKSH

Great initiative; even today lots of users still post links to Qt 5.0 documentation.

I don't know if you're aware of these or not, but webmaster tools (e.g. https://www.google.com/webmasters/tools/ and http://www.bing.com/toolbox/webmaster ) are very useful for cleaning up a site's search results.

jpasion

Hello,

Yes, we are quite involved with
Google Analytics
Google Webmaster Tools
Google Custom Search Engine

I haven't looked too much at the Bing results yet, mostly because we use the Google Analytics trackers. I've also taken a look at the yandex and duckduckgo (I use the latter).

Most of the changes we implemented to the HTML were only deployed during the Qt 5.2 release, which was in December 2013. The data in 2014 is in-line with our expectations.

sierdzio

I have replied to the thread on the mailing list, but to reiterate: +1 from me. In my opinion, only the newest docs should be on the site, to avoid confusion and overflowing Google results.

If somebody needs a specific version of the documentation, they probably also have that specific version of Qt installed, with all the local documentation.

jpasion

Hello all,

Thanks for the feedback.

We plan to deploy the redirects next week to avoid the Easter break; hopefully, Monday.

Some more notes:
A) The Qt 5.0, 5.1, and 5.2 documentation sets are already hosted in the archives: http://doc.qt.digia.com/archives/index.html
There will be links to them from qt-project.org/doc/.

B) I modified the Qt Project search filters to include the Archives, Code Review, Mailing Lists, and Bug Reports.

C) The Qt Project members who made revisions (created or edited) doc notes have already received a mail about the doc notes. The doc notes won't be removed and they are still visible from the the member's pages. There were some bugs and limitation in the current doc notes implementation that prevents us from trivially porting the doc notes over.

Cheers,
Jerome P.
Documentation Engineer - Digia, Qt