Use stable version URLs for documentation

[Brian Moss]

This issue has been split from Bug #1479166 to capture the request of Martin Paulo in comment #3

---

As a developer the OpenStack documentation can be very frustrating. Let me try to explain...

Faced with a problem, I turn to Google, which gives me links that look as though they might help me. Say one is to a blog posting, or to Stack Overflow. This article provides good information, but contain links to the OpenStack documentation for more detail. So I click on the link, only to find that the page no longer exists.

So I turn to Google again, trying to find this new information. But Google itself either contains links that are either outdated (so I have to go the cache, not always guaranteed to work) or that take me to pages that exist: but turn out to be part of some older documentation set (I haven't experienced this for a while, so don't know if this is fixed or not). Clicking around the older documentation set results in total confusion as you get launched into new parts of the site. And you don't find what you are looking for...

Could you please migrate the documentation to stable urls (as per http://www.w3.org/Provider/Style/URI.html)? I suggest the Django documentation as an example to follow. See https://docs.djangoproject.com/en/1.4/ vs https://docs.djangoproject.com/en/1.8/ vs https://docs.djangoproject.com/en/ for an example of how they manage this...

This would have the added advantage of allowing people who are on older versions of OpenStack to still have easy access to the relevant documentation.

Thank you!

[Brian Moss (bmoss)]

From what I can see, we have stable URLs:

http://docs.openstack.org/liberty/
vs
http://docs.openstack.org/mitaka/

http://docs.openstack.org/liberty/install-guide-ubuntu/
vs
http://docs.openstack.org/mitaka/install-guide-ubuntu/

The addition of watermarks to versioned books should help with some of the problems that arise from linking into the docs from other sources.

I think this is still a problem though: "clicking around the older documentation set results in total confusion as you get launched into new parts of the site."

In other words, if you select 'Liberty' in the 'More Releases & Languages' dropdown, you are taken to the http://docs.openstack.org/liberty/ index page. So far so good.

If you click 'Administrator Guide' you are taken to http://docs.openstack.org/admin-guide/. This is correct, as the Administrator Guide is not versioned.

However, if you now use the 'OpenStack Documentation' dropdown to select 'Install Guides', you are taken to http://docs.openstack.org/index.html#install-guides. This is not expected as the user originally selected 'Liberty' and expects to arrive at the Liberty Install Guide.

[Tom Fifield (fifieldt)]

Since people continually have a bad experience, and using incorrect documentation for your release version continues to cause major confusion, marking as critical based on our guidelines "it's so bad that we're better off fixing it than dealing with all the incoming questions about it" and "items on the website itself that prevent access"

http://docs.openstack.org/contributor-guide/doc-bugs.html#doc-bug-triaging-guidelines

[Tom Fifield (fifieldt)]

Copying over an extra comment from Bug #1479166:

Cristina Aiftimiei (caifti) wrote on 2016-11-09: #22

Hi,

I was adviced to add some comments to this bug regarding the issue that I see with the documentation:
""""
n the last days I'm looking around for an old link that I had on how to
configure "Provider networks with Open vSwitch"in Juno release.
I had the link
http://docs.openstack.org/kilo/networking-guide/scenario_provider_ovs.html
that now give s a nice "404"
Going to the Juno documentation - http://docs.openstack.org/juno/ - one
can lcearly see that under the "Networking Guide" there is a lin
pointing to the "wrong" release -
http://docs.openstack.org/kilo/networking-guide/, from where one can
reach the:
http://docs.openstack.org/kilo/networking-guide/scenario_provider_ovs.html

None of the documents under the " Operations and Administration Guides "
point anymore to the "juno" version.

As we have still a/some testbed with the Juno version I would like to
ask you if you know of a place where "obsoleted" documentation is moved.
As there are still the installation guides for this version I would
expect that at least a trace of the Operation & Administration ones is
kept.
At least as vintage collection I would like to be able to read it once
more
"""

Hope this could improve the documentation by making people aware that it's not a good thing to make dissapear documentation. Versioning, archiving, whatever method you can think good to keep a bit of history would be very much welcome.

Thank you,
Cristina

[Tom Fifield (fifieldt)]

Related bug: https://bugs.launchpad.net/openstack-manuals/+bug/1658659

[Alexandra Settle (alexandra-settle)]

These issues are bigger than this bug report alone, unfortunately. The documentation community has begun the process of dealing with the matter of archiving documentation accordingly.

At the moment - all URLs of previous documentation should be stable, and redirected to the current updated documentation suite. In that case, the problem of this bug is solved and should be marked as such.

Please note that we will be continuing efforts to ensure that this issue is solved in the future.

More information can be found here: https://review.openstack.org/#/c/426047/1 and https://blueprints.launchpad.net/openstack-manuals/+spec/archiving

This bug has been linked to the blueprint, and will be continued to be used for tracking purposes alone.

[Daniel Bengtsson (damani42)]

Hi there,

Do we have any update here, it's still relevant?