Harmonizing the Qt 5.x Documentation



  • 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


  • Lifetime Qt Champion

    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



  • Hello,

    Thanks for the idea. I will do that.

    Cheers.


  • Moderators

    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.



  • 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.


  • Moderators

    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.



  • 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


Log in to reply
 

Looks like your connection to Qt Forum was lost, please wait while we try to reconnect.