[Development] Harmonizing the Qt 5.x Documentation

Andre Somers andre at familiesomers.nl
Tue Mar 11 17:17:46 CET 2014


Matthew Woehlke schreef op 11-3-2014 17:04:
> 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.)
Indeed. It seems like a Bad Idea(TM) to me.
>
>> 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...
That would suck too... As the on-site search for the docs is quite bad, 
I resort to using the Qt Doc Search extension for Chrome to search for 
documentation with the right version. That works quite well, but would 
break if either the old docs are removed they are not allowed to be 
indexed any more.

I seriously don't see the benefit of this "harmonization". When I look 
at the docs for a class, I often just look for method names that seem to 
do what I need. That usually works very with Qt. Now, I will need to go 
check for every method if it actually exists in the version of Qt I'm 
on, by looking for a "since" tag. How is that helping me to become more 
productive?

André




More information about the Development mailing list