[Development] Preventing link rot in Qt docs

[Sze Howe Koh]

In the transition from Qt 5.11 to Qt 5.12, some doc URLs have changed,
for example:

https://doc.qt.io/qt-5/android-support.html ->
https://doc.qt.io/qt-5/android.html
https://doc.qt.io/qt-5/androidgs.html ->
https://doc.qt.io/qt-5/android-getting-started.html

While I do like the new URLs better, the old URLs now give Error 404.
This is a problem because the Qt docs are heavily cited in the forums,
the wiki, and external sites like StackOverflow. Search engines also
take time to catch up, e.g. the top two results are currently dead at
https://www.google.com/search?q=site%3Adoc.qt.io%2Fqt-5+android

Is it feasible to make doc redirections an integral part of the
release process? Diffing the list of HTML files produced by qdoc
should help a lot.


Regards,
Sze-Howe

[Mitch Curtis]

+1, great idea.

> -----Original Message-----
> From: Development <development-***@lists.qt-project.org> On
> Behalf Of Sze Howe Koh
> Sent: Friday, 7 December 2018 1:47 PM
> To: Qt development mailing list <***@qt-project.org>
> Subject: [Development] Preventing link rot in Qt docs
>
> In the transition from Qt 5.11 to Qt 5.12, some doc URLs have changed, for
> example:
>
> https://doc.qt.io/qt-5/android-support.html -> https://doc.qt.io/qt-
> 5/android.html
> https://doc.qt.io/qt-5/androidgs.html -> https://doc.qt.io/qt-5/android-
> getting-started.html
>
> While I do like the new URLs better, the old URLs now give Error 404.
> This is a problem because the Qt docs are heavily cited in the forums, the
> wiki, and external sites like StackOverflow. Search engines also take time to
> catch up, e.g. the top two results are currently dead at
> https://www.google.com/search?q=site%3Adoc.qt.io%2Fqt-5+android
>
> Is it feasible to make doc redirections an integral part of the release process?
> Diffing the list of HTML files produced by qdoc should help a lot.
>
>
> Regards,
> Sze-Howe
> _______________________________________________
> Development mailing list
> ***@lists.qt-project.org
> https://lists.qt-project.org/listinfo/development

[Elvis Stansvik]

Den fre 7 dec. 2018 15:36Mitch Curtis <***@qt.io> skrev:

> +1, great idea.
>

+1 from me to, if possible, even if it's a bit of work,
https://www.w3.org/Provider/Style/URI

Elvis


> > -----Original Message-----
> > From: Development <development-***@lists.qt-project.org> On
> > Behalf Of Sze Howe Koh
> > Sent: Friday, 7 December 2018 1:47 PM
> > To: Qt development mailing list <***@qt-project.org>
> > Subject: [Development] Preventing link rot in Qt docs
> >
> > In the transition from Qt 5.11 to Qt 5.12, some doc URLs have changed,
> for
> > example:
> >
> > https://doc.qt.io/qt-5/android-support.html -> https://doc.qt.io/qt-
> > 5/android.html
> > https://doc.qt.io/qt-5/androidgs.html ->
> https://doc.qt.io/qt-5/android-
> > getting-started.html
> >
> > While I do like the new URLs better, the old URLs now give Error 404.
> > This is a problem because the Qt docs are heavily cited in the forums,
> the
> > wiki, and external sites like StackOverflow. Search engines also take
> time to
> > catch up, e.g. the top two results are currently dead at
> > https://www.google.com/search?q=site%3Adoc.qt.io%2Fqt-5+android
> >
> > Is it feasible to make doc redirections an integral part of the release
> process?
> > Diffing the list of HTML files produced by qdoc should help a lot.
> >
> >
> > Regards,
> > Sze-Howe
> > _______________________________________________
> > Development mailing list
> > ***@lists.qt-project.org
> > https://lists.qt-project.org/listinfo/development
> _______________________________________________
> Development mailing list
> ***@lists.qt-project.org
> https://lists.qt-project.org/listinfo/development
>

[Richard Weickelt]

On 07.12.2018 18:09, Giuseppe D'Angelo via Development wrote:
> Il 07/12/18 13:46, Sze Howe Koh ha scritto:
>> This is a problem because the Qt docs are heavily cited in the forums,
>> the wiki, and external sites like StackOverflow.
>
> As an add-on, keep the documentation online, but use properly versioned
> URLs, so that these breaks never happen. (Of course one could have a big fat
> warning on top of earlier versions saying that one is reading an old version
> of the docs.)

This is already the case:

https://doc.qt.io/qt-5/android.html
https://doc.qt.io/qt-5.12/android.html
https://doc.qt.io/qt-5.11/android-support.html

https://doc.qt.io/qt-5/android-getting-started.html
https://doc.qt.io/qt-5.12/android-getting-started.html
https://doc.qt.io/qt-5.11/androidgs.html

But I agree with Sze-Howe: It would be convenient if renaming pages would
also include replacing the old URL by a 301 redirect to the new one.

Richard

[Topi Reiniö]

Redirects are now in place. We have also plans to implement better versioning for the online docs.


\topi

________________________________
From: Development <development-***@lists.qt-project.org> on behalf of Richard Weickelt <***@weickelt.de>
Sent: Friday, December 7, 2018 10:56:43 PM
To: ***@lists.qt-project.org
Subject: Re: [Development] Preventing link rot in Qt docs

On 07.12.2018 18:09, Giuseppe D'Angelo via Development wrote:
> Il 07/12/18 13:46, Sze Howe Koh ha scritto:
>> This is a problem because the Qt docs are heavily cited in the forums,
>> the wiki, and external sites like StackOverflow.
>
> As an add-on, keep the documentation online, but use properly versioned
> URLs, so that these breaks never happen. (Of course one could have a big fat
> warning on top of earlier versions saying that one is reading an old version
> of the docs.)

This is already the case:

https://doc.qt.io/qt-5/android.html
https://doc.qt.io/qt-5.12/android.html
https://doc.qt.io/qt-5.11/android-support.html

https://doc.qt.io/qt-5/android-getting-started.html
https://doc.qt.io/qt-5.12/android-getting-started.html
https://doc.qt.io/qt-5.11/androidgs.html

But I agree with Sze-Howe: It would be convenient if renaming pages would
also include replacing the old URL by a 301 redirect to the new one.

Richard