[Interest] Flat directory structure for Qt 5.2 documentation

Pasion Jerome Jerome.Pasion at digia.com
Mon Sep 23 17:59:50 CEST 2013


Hello,

The 'stable' and 'dev' links in doc-snapshot.qt-project.org now points to the flat directory structure. I also removed the qt5-nosubdir link.

for 5.2:
-current tasks for 5.2 are in https://bugreports.qt-project.org/browse/QTBUG-32173 these are mostly new features for 5.2 and the editing tasks are still ongoing.

About the redirects:
-setting up redirects is not smart to do now, just before 5.2 is released because the changes are a bit more involved than just creating a mapping of directories. (we have 3 sites hosted by 2 ISPs)
-the contents of doc.qt.digia.com and the redirects associated with it will be looked at after 5.2 is released.
-the flat structure for online content will definitely help. I would rather see how this structure develops and perceived before doing anything drastic.

About the content:
-feel free to file a bug and let us know which pages you were looking at. Otherwise, suggestions and general complaints get ignored or lost.
-the 3-tiered structure remains the same from Qt 3. We have Overviews, Reference, and Examples. Much of the overviews were re-written or removed for Qt 5 because of irrelevancy, lack-of-focus, and incorrect information.
-the documentation scope changed moving to Qt 4 and Qt 5, especially after Qt Project was launched. Non-"Qt Reference" materials were moved outside of the reference pages and onto the main Qt Project site.
-the content needs polishing, for sure, but without any proper feedback, we don't have a problem to solve.

Cheers,
Jerome P.
Documentation Engineer - Digia, Qt

________________________________
Fra: Pasion Jerome
Sendt: 30. august 2013 14:23
To: development at qt-project.org; interest at qt-project.org
Emne: Flat directory structure for Qt 5.2 documentation

Hello all,

For Qt 5.2, we plan to deliver the online documentation (qt-project.org/doc)
using a flat documentation structure. Currently, the online documentation
is using the modularized structure.

By default, Qt 5 source builds will still use the modularized structure and only
the online Qt documentation (qt-project.org/doc/qt-5) will receive the single-
directory documentation. The snapshots (doc-snapshot.qt-project.org) will serve
as testing ground for the single-directory documentation.

Snapshot: http://doc-snapshot.qt-project.org/qt5-nosubdir/
***Please don't spread this link because this is for testing only.
I will remove it once 'dev' is merged to 'stable'.***

So, it is even more important that the HTML filenames are unique. We're going
through the list of warnings produced by QDoc and most of the duplicate file
warnings are about example names. Try to employ meaningful example names in the
context of Qt, not just within that module.

Current QDoc warnings: https://bugreports.qt-project.org/browse/QTBUG-32580

More information about the specifications and guidelines is available at:
http://qt-project.org/wiki/QtWritingGuidelines

There are other plans regarding how the redirects work once the single-directory
documentation is more mature and those will be communicated later. As well,
we are improving the usability and navigation of the content in reference
documentation ('dev' branches).

Cheers,
Jerome Pasion
Documentation Engineer - Digia, Qt
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20130923/3e1afdf9/attachment.html>


More information about the Interest mailing list