[Interest] 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 ___ Interest mailing list Interest@qt-project.org http://lists.qt-project.org/mailman/listinfo/interest
Re: [Interest] Harmonizing the Qt 5.x Documentation
Il 11/03/2014 10:01, Pasion Jerome ha scritto: -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. Why not? They might represent actual bugs or improvements for the documentation. Instead of dropping them altogether it would be better to turn them into JIRA reports so they can be evaluated and merged in the docs, if possible (then we can think of ditch or redesign the entire feature). Regards, -- Join us Oct 6-8 at BCC Berlin for Qt Developer Days 2014! Giuseppe D'Angelo | giuseppe.dang...@kdab.com | Software Engineer KDAB (UK) Ltd., a KDAB Group company Tel. UK +44-1738-450410, Sweden (HQ) +46-563-540090 KDAB - Qt Experts - Platform-independent software solutions smime.p7s Description: Firma crittografica S/MIME ___ Interest mailing list Interest@qt-project.org http://lists.qt-project.org/mailman/listinfo/interest
Re: [Interest] Harmonizing the Qt 5.x Documentation
On 2014-03-11 05:01, Pasion Jerome wrote: 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/). How am I then supposed to find the 5.x documentation if I am developing an application against 5.x but the latest release is 5.y? It's common practice to keep old documentation available so that users can have a correct view of the state of the software /as of the version they are using/. If you don't do this, you *MUST* accurately document every *change* (not just additions) between versions and have that documentation clearly visible in the documentation of the affected classes/methods/etc. (Plus, I know from experience that \since is easily overlooked.) 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. That can be solved easily by having /doc/qt-5/ symlinked on the server to the latest 5.x. I would also encourage doing like python.org and adding a widget to select the documentation version. You could also add a big noisy warning to the historic documentation pages. 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. So don't allow these to be indexed? I know there are ways to tell search engines to not index certain pages... -- Matthew ___ Interest mailing list Interest@qt-project.org http://lists.qt-project.org/mailman/listinfo/interest
Re: [Interest] Harmonizing the Qt 5.x Documentation
Em ter 11 mar 2014, às 12:04:11, Matthew Woehlke escreveu: On 2014-03-11 05:01, Pasion Jerome wrote: 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/). How am I then supposed to find the 5.x documentation if I am developing an application against 5.x but the latest release is 5.y? First of all, you should read the latest documentation. It contains the notices saying when classes and methods were added so you will know whether they apply to you. Plus, you get updates and fixes for the docs that have happened since that release, as well as comments by users on the website. Second, if you really want that documentation, it came with your 5.x release. Just load it in Creator or Assistant. It's common practice to keep old documentation available so that users can have a correct view of the state of the software /as of the version they are using/. If you don't do this, you *MUST* accurately document every *change* (not just additions) between versions and have that documentation clearly visible in the documentation of the affected classes/methods/etc. (Plus, I know from experience that \since is easily overlooked.) We document only additions. Improvements to the docs don't make sense. Bugfixes to the code don't need documentation either: if you're using intentionally an old version, you are subject to corrected bugs and you know it. I could agree to behaviour changes, however rare: whenever there's a behaviour change, it should be documented in the class docs. I would also encourage doing like python.org and adding a widget to select the documentation version. You could also add a big noisy warning to the historic documentation pages. That would be nice. MSDN does the same per MSVC version too. -- Thiago Macieira - thiago.macieira (AT) intel.com Software Architect - Intel Open Source Technology Center ___ Interest mailing list Interest@qt-project.org http://lists.qt-project.org/mailman/listinfo/interest
