Identify old pages on docs.openstack.org

[Lana]

When browsing docs.openstack.org, it's not always obvious how old the information you are looking at might be. In the old Docbook docs, we used a watermark that contained the release name as a stop-gap, however with the conversion to RST, even that functionality has been removed. This bug is to track development of a method of identifying how old content is (which may be a less-subtle watermark, or some other novel bit of design).

(This bug has been created to more accurately track the problems identified in bug #1191447. The old bug has been closed, conversation continues here. For historical context, see https://bugs.launchpad.net/openstack-manuals/+bug/1191447)

[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".

https://wiki.openstack.org/wiki/Documentation/HowTo#Doc_Bug_Triaging_Guidelines

[Tom Fifield (fifieldt)]

Changed the heading of the bug, since this is not solved in docbook docs either, so not specific to RST

[Martin Paulo (martin-paulo)]

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)]

I've built a Sphinx extension that enables adding watermark images to HTML output. Next step is adding the extension PyPI then including it in the openstack-manuals build. I'm away for the next few weeks, but I'll pick this up again when I get back.

[Brian Moss (bmoss)]

The basic premise is here: https://github.com/kallimachos/sphinxmark

I'm working on some enhancements and general tidying. Initial tests suggest this approach works with the openstackdocstheme.

Stay tuned.

[Brian Moss (bmoss)]

sphinxmark is working in my local tests with openstack-manuals. Huzzah!

I'll get some patches up for review next week.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/mitaka
Review: https://review.openstack.org/365397

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/liberty
Review: https://review.openstack.org/365403

[OpenStack Infra (hudson-openstack)]

Change abandoned by Brian Moss (<email address hidden>) on branch: master
Review: https://review.openstack.org/362497

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/365872

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/365872
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=aa4ff78daf8ade05408700d1050b8988a228f271
Submitter: Jenkins
Branch: master

commit aa4ff78daf8ade05408700d1050b8988a228f271
Author: Brian Moss <email address hidden>
Date: Tue Sep 6 15:54:30 2016 +1000

    Add watermark to Newton versioned guides

    Adds a Newton watermark to the Install Guides,
    Networking Guide, and Config Ref Guide.

    Change-Id: I0e4f2942b87d996e9f2fd419f808578636d07e78
    Backport: mitaka liberty
    Partial-bug: #1479166

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/365403
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=40a0a93906fcae81db633afa001ec4698cc63ebb
Submitter: Jenkins
Branch: stable/liberty

commit 40a0a93906fcae81db633afa001ec4698cc63ebb
Author: Brian Moss <email address hidden>
Date: Mon Sep 5 12:45:51 2016 +1000

    Add watermark to Liberty versioned guides

    Adds a Liberty watermark to the Install Guides,
    Networking Guide, and Config Ref Guide.

    Change-Id: Ie0e80d4c506c2c036bdfbe8ecc93ad8646e051d3
    Partial-bug: #1479166

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/365397
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=ed441aceef11e98046f3e8267e010dd335f1359a
Submitter: Jenkins
Branch: stable/mitaka

commit ed441aceef11e98046f3e8267e010dd335f1359a
Author: Brian Moss <email address hidden>
Date: Mon Sep 5 12:07:35 2016 +1000

    Add watermark to Mitaka versioned guides

    Adds a Mitaka watermark to the Install Guides,
    Networking Guide, and Config Ref Guide.

    Change-Id: I9845bfb14d8142edda182d48ca60a08b2de19f65
    Partial-bug: #1479166

[Brian Moss (bmoss)]

Patches for Newton, Mitaka, and Liberty have merged. We can keep using the sphinxmark extension for future releases. I believe that addresses this bug.

[Tom Fifield (fifieldt)]

Many thanks Brian - watermark gets us back to the previous (better) state, but doesn't solve this bug fully. See eg comment #3 and the comments in the previous bug.

[Brian Moss (bmoss)]

Ah, you're right. Thanks Tom.

I'm actually going to split this into two bugs, because I think that creating stable URLs and adding watermarks are two different tasks. Plus, it sounds like we need some more discussion on the watermark design so it will be helpful to keep the two threads separate.

[Brian Moss (bmoss)]

I've split this into two bugs:

Bug #1621683 - Apply watermark to old pages on docs.openstack.org

Bug #1621685 - Use stable version URLs for documentation

[Brian Moss (bmoss)]

On second thought, we don't really need a new bug to track watermark work. Let's keep doing that here.

sphinxmark (https://github.com/kallimachos/sphinxmark) is a sphinx extension for adding watermarks to Sphinx documentation. We are currently using it to display watermarks in the Installation Guides, Networking Guide, and Config Ref. These text-based watermarks display behind the content text and can be adjusted for color, size, and opacity.

While this design does the basic job of notifying users about the version they are reading, there are other design options we can also consider.

Things we can do with the existing config:

- Reduce the opacity of the watermarks. Some users find the current setting distracting and reducing the opacity would make the watermarks less visible.
- Remove watermarks from current versions of docs and display them only on earlier versions.
- Remove watermarks entirely until we reach consensus on the design

Some enhancements discussed on the docs ML have already been submitted as issues to sphinxmark:

- Support border watermark (similar to the look we had with XML docs)
- Add option to set spacing between text-based watermarks
- Add image repeat option

[Brian Moss (bmoss)]

Another design possibility is a sticky version in one corner similar to http://docs.readthedocs.io/en/latest/theme.html

[Anne Gentle (annegentle)]

I think a watermark is a print-centric design and while we can have it, sure, a web-centric design that lets readers get to other versions is a better outcome all 'round.

Here's my super lame first attempt to implement such a thing:

https://review.openstack.org/367725

Feel free to poke at it and see if it's useful.

[Brian Moss (bmoss)]

I've made some changes to https://review.openstack.org/367725 and now the basic functionality and appearance are in place.

We need some logic to obtain a list of versions and retain the currently selected version when navigating between pages.

Sphinxmark has also been updated with the following options:
- text-based watermark spacing and rotation can be configured
- watermark can occur once or repeat down page
- watermark can be fixed or scroll with page
- watermark can be applied as a border next to the content rather than behind it

[Cristina Aiftimiei (caifti)]

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

[KATO Tomoyuki (kato-tomoyuki)]

At now, we have watermarks. Thank you, Brian.