Collection of design and experience issues with docs.openstack.org

This has annoyed me for a while as well :) Marking as critical so we will actually take action to remove/mark outdated information with priority.

For a first step, I'm marking "close comments" in the Admin Dashboard for old sites, making threads disabled after 365 days.

http://help.disqus.com/customer/portal/articles/466243-how-do-i-close-comment-threads-

The other aspect I'd like to check we've solved is the old problem where after page renames, the old-named page still exists. Is this fixed, or still the case?

Yah, there's a root cause problem I'd like to solve, where none of the doc build jobs delete the built HTML file after the source is deleted. See https://bugs.launchpad.net/openstack-ci/+bug/1096126. We could file a second bug but that one is the bug technically.

Reviewed: https://review.openstack.org/35022
Committed: http://github.com/openstack/openstack-manuals/commit/ae69c5c866f8ba9156a9ba40fccff49a7d12fbe4
Submitter: Jenkins
Branch: master

commit ae69c5c866f8ba9156a9ba40fccff49a7d12fbe4
Author: Tom Fifield <email address hidden>
Date: Sun Jun 30 16:18:02 2013 +1000

    Mark diablo, essex and folsom with their status

    This patch marks the landing pages of non-maintained releases
    with appropriate information.

    patchset2 addresses Anne's comments
    patchset4 - diane fleming - made editorial changes

    fixes bug 1191447

    Change-Id: Ia90d86a3328ec293e654886d3417d2d846cb8430

There's more work to be done, design work with a designer, to make this even more clear throughout navigation.

found another page that needs deletion: http://docs.openstack.org/trunk/openstack-network/admin/content/nova_with_neutron_vifplugging_nvp.html

Hmm, I was wrong actually. Damn.

Can we tie this to SEO too? I've just experienced lots of 404s when Googling - where I end up in URI stems that no longer exist, e.g. http://docs.openstack.org/admin-guide-cloud/content/compute-options-reference.html

Can we do some rewriting to punt them to the right place (or at least a 404 page that make navigating to the right place easier?)

The 404s are because of redirecting from /trunk/. I think we will have to
be more exact in the htaccess file especially to point people to the
compute-options-referenence.html because this is the second time that
particular one has been reported.

On Mon, Sep 23, 2013 at 4:17 AM, Kevin Jackson
<email address hidden>wrote:

> Can we tie this to SEO too? I've just experienced lots of 404s when
> Googling - where I end up in URI stems that no longer exist, e.g.
> http://docs.openstack.org/admin-guide-cloud/content/compute-options-
> reference.html
>
> Can we do some rewriting to punt them to the right place (or at least a
> 404 page that make navigating to the right place easier?)
>
> --
> You received this bug notification because you are subscribed to
> OpenStack.
> https://bugs.launchpad.net/bugs/1191447
>
> Title:
> Clearly mark outdated doc pages
>
> Status in OpenStack Manuals:
> Confirmed
>
> Bug description:
> We still get disqus comments on very old doc pages (e.g., I replied to
> one today that was on a diablo(!) page).
>
> If we are going to keep these around, it would be helpful if they were
> clearly labelled as being out of date.
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/openstack-manuals/+bug/1191447/+subscriptions
>

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

Reviewed: https://review.openstack.org/47845
Committed: http://github.com/openstack/openstack-manuals/commit/dcc2a35153fd9bc06dd90c9d912811d9cc4cbf2a
Submitter: Jenkins
Branch: master

commit dcc2a35153fd9bc06dd90c9d912811d9cc4cbf2a
Author: annegentle <email address hidden>
Date: Mon Sep 23 09:12:38 2013 -0500

    Precisely redirects compute-options-reference.html to new location

    Change-Id: Iaa02cb4c8f85a9a9ab210110827e0b7661abc73b
    Partial-bug: 1191447

One other idea would be to use the watermark feature we have, where it outputs DRAFT all along the side of each page, but instead output OUTDATED or some such. Thoughts?

In my experience that wouldn't have such a big impact. Operators are so used to only having outdated content to work from, a subtle watermark is not enough to make them choose another document ... instead they'll stick with the first one they found and extrapolate from it until it no longer solves their problem :)

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

Reviewed: https://review.openstack.org/53036
Committed: http://github.com/openstack/openstack-manuals/commit/d933ec7fec53217f2b16dc572f79cc461ab59621
Submitter: Jenkins
Branch: master

commit d933ec7fec53217f2b16dc572f79cc461ab59621
Author: annegentle <email address hidden>
Date: Mon Oct 21 18:44:15 2013 -0500

    Updates sitemap.xml for havana release links

    Adds an XSLT that transforms a generated sitemap, removing folsom
    and trunk links

    backport: stable/havana

    Change-Id: I4484d50fa60eb53e3155fe4e119c30e54b03832e
    Partial-bug: 1191447

This is still a big issue, and old references continue to crop up in google and on mailing lists posts.

I have done the following:
- finer tuning of the Google Custom Search Engine. However I can't figure out if the Foundation has a second CSE that they are tuning. Can you find out Tom?
- asked Todd Morey for a redesign. I continue to pursue this.
- asked for more design ideas

Any other ideas here?

Get a dump of the apache logs to see the raw requests coming in, and keep twiddling until everything's hitting something that is either in-date, or has a HUUUUGGEEEE message explaining it's out of date.

and fix one of the underlying problems, where old HTML files still exist on the server

On the front page, fo docs that are old, but still 'valid', put a tip next to its name (for example, 'under construction' or 'valid for Grizzly'.

These two pages are getting over 1,000 hits a day.
/trunk/openstack-identity/admin/content/creating-tenants-users-roles-tokens-and-endpoints.html

/trunk/openstack-identity/admin/content/curl-examples.html

Deleting and giving a redirect for those two.

Also, /trunk/openstack-compute/install/content/ needs deleting.

admin-guide-cloud/content/ch-identity-mgmt-config.html#keystone-admin-concepts is what I'll redirect those top two to.

https://review.openstack.org/#/c/62072/ - merged

annegentle suggesting leaving a comment here:

Many searches seem to hit pages in the Grizzly network admin guide at http://docs.openstack.org/grizzly/openstack-network/admin/content/. All the results in Google include a double slash after "content/", for example:

  http://docs.openstack.org/grizzly/openstack-network/admin/content//adv_cfg_l3_agent_multi_extnet.html

This results in a variety of problems (no images, no css, etc). Just handling this one case would make a number of pages display correctly.

Possibly including a link pointing at the current cloud-admin guide would also be helpful.

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

commit b943ff1d35b27d859eb6ddcb4dfe0c45259fa9e1
Author: Anne Gentle <email address hidden>
Date: Thu Feb 6 16:35:09 2014 -0600

    Revise htaccess to avoid double slashes when redirecting

    Change-Id: If08c289480f8cab0727df9975c1f605e77376100
    Partial-bug: 1191447

URL: http://docs.openstack.org/training-guides/content/lab001-control-node.xml.html is another page that has confused people

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

Additional issues:

404 - http://docs.openstack.org/cli/quick-start/content/glance_client.html
      (found at http://docs.openstack.org/grizzly/openstack-compute/admin/content/ch_image_mgmt.html)

404 - http://docs.openstack.org/cli/quick-start/content/nova_client.html
      (found at http://docs.openstack.org/grizzly/openstack-compute/admin/content/associating-public-ip.html)

404 - http://docs.openstack.org/grizzly/openstack-compute/admin/openstack-compute/admin/content/ch_cells.html
      (found at http://docs.openstack.org/grizzly/openstack-compute/admin/content/compute-options.html)

http://docs.openstack.org/grizzly/openstack-compute/admin/bk-compute-adminguide-grizzly.pdf

from https://bugs.launchpad.net/openstack-manuals/+bug/1228721

Please do .htaccess updates for the 404 errors found.

On Sat, Mar 29, 2014 at 9:11 PM, Tom Fifield <email address hidden>wrote:

> Additional issues:
>
> 404 - http://docs.openstack.org/cli/quick-start/content/glance_client.html
> (found at
> http://docs.openstack.org/grizzly/openstack-compute/admin/content/ch_image_mgmt.html
> )
>
> 404 - http://docs.openstack.org/cli/quick-start/content/nova_client.html
> (found at
> http://docs.openstack.org/grizzly/openstack-compute/admin/content/associating-public-ip.html
> )
>
> 404 -
> http://docs.openstack.org/grizzly/openstack-compute/admin/openstack-compute/admin/content/ch_cells.html
> (found at
> http://docs.openstack.org/grizzly/openstack-compute/admin/content/compute-options.html
> )
>
> http://docs.openstack.org/grizzly/openstack-compute/admin/bk-compute-
> adminguide-grizzly.pdf
>
> from https://bugs.launchpad.net/openstack-manuals/+bug/1228721
>
> --
> You received this bug notification because you are subscribed to
> OpenStack.
> https://bugs.launchpad.net/bugs/1191447
>
> Title:
> Clearly mark outdated doc pages
>
> Status in OpenStack Manuals:
> Confirmed
>
> Bug description:
> We still get disqus comments on very old doc pages (e.g., I replied to
> one today that was on a diablo(!) page).
>
> If we are going to keep these around, it would be helpful if they were
> clearly labelled as being out of date.
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/openstack-manuals/+bug/1191447/+subscriptions
>

From https://bugs.launchpad.net/openstack-manuals/+bug/1145392
 Prominently feature release on HTML output rather than just in URL

putting the version somewhere prominently on the page (say, the upper right hand corner, above "<prev|up|next>").

What about the "Deprecated" status bar text as shown on this page?
http://docs.rackspace.com/servers/api/v1.0/cs-releasenotes/content/ch_preface.html

This will be addressed with:
https://review.openstack.org/110793

Saw some nice watermarking for outdated pages at: http://www.dcache.org/manuals/Book-2.5/cookbook/cb-proto-dcap-ext.shtml :D

We have a path forward, and I think this bug has served its purpose. Marking fix released.

A path forward is not the same as bug fixed :) The bug should remain open until the problem is solved.

Tom, can you be more specific about the feedback you've received? Is it on the RST docs? Is it for a particular title? How are they coming in to the page? Please be more specific so we can find solutions.

Easy one to start with:

People land on a page with a version they're not looking for and then can't move to a different version from that page

Random idea: a subtle/background colour highlight per release. So we eventually train people that Kilo=Red, Juno=Purple, etc.

More random feedback:

I followed a link from ask.openstack.org to a specific document and it transferred me to the index of a different version of the document.

Color legends are not recommended by anyone.

I'd like to see a new bug opened for the specific link from ask.openstack.org please.

For "can't move to a different version from that page" did we have that movement as a requirement in the web redesign? I'd like a new bug for that as well so we can get specific about solutions.

I'm sorry, is there a doubt that there isn't a larger general problem here?

Additionally, what's with the blanket rejection of a brainstorming suggestion ?

Jump on google and put in something like "use of color in communication" - there's a ton of good stuff.

Not at all! There's a larger general problem that needs to be chunked into smaller solutions.

Color in communication, sure, but if we solve with color shouldn't that be a new bug? We're at number 43 comment now, is that the best way to find real solutions to individual design issues?

More random ideas:

Work in the release logos somehow:

* https://www.openstack.org/assets/software/kilo/kilo-logo.png
* https://www.openstack.org/assets/software/juno/juno-logo.png
* https://www.openstack.org/themes/openstack/images/icehouse/icehouse-logo.png
* https://www.openstack.org/themes/openstack/images/havana/havana.png
* https://www.openstack.org/themes/openstack/images/grizzly/grizzly.png

Hammer that it is, I still feel like a big general bug is the best way we have to track the overall problem. Not opposed to creating smaller bugs, but I think something needs to remain open to track the issue at the highest level and ensure that after all of those smaller bugs are solved the actual issue is done and dusted.

Our other tools: Launchpad blueprints (tracking ability, no real ability to comment) and files in the docs-specs repositories (no tracking ability, tedious to update) don't cut the mustard in this regard (and neither of them are places we can send users to to give speils, in the rare case we find someone willing to spend the time)

I feel as though the general thrust of this bug has been resolved. Tom, do you have specific things that you think still need to be addressed here?

I have to disagree - this is still very much a general problem. Perhaps I'm missing something, but how has the bug been resolved?

The original bug was about marking old docs pages to make readers more aware of their age. We implemented the release name watermark to try and counteract that original problem. Additionally, with the RST conversion and the new docs theme, we are increasingly moving away from the old styles, anyway, which is resolving some of the other niggling usability issues that are touched on here.

What do you see as the core issue here?

Hi yup,

So, the watermark was a stop-gap we could do quickly - never intended as full solution to the problem. If the RST conversion was the eventual solution, this bug should remain open until it is completed.

However, unfortunately, the RST template doesn't actually do anything to mark outdated doc pages :)

If you have an idea for the template design then please log a new bug with
a description of the issue. The template design was tested and vetted after
November 2014, so I sense there's a disconnect in tracking that may be
better solved with a new issue describing the problem better. This one is
stale, has too many comments, and has become conflated with redirect issues
and version surfacing rather than the issue you just listed.

On Mon, Jun 22, 2015 at 12:27 AM, Tom Fifield <email address hidden>
wrote:

> Hi yup,
>
> So, the watermark was a stop-gap we could do quickly - never intended as
> full solution to the problem. If the RST conversion was the eventual
> solution, this bug should remain open until it is completed.
>
> However, unfortunately, the RST template doesn't actually do anything to
> mark outdated doc pages :)
>
> --
> You received this bug notification because you are subscribed to a
> duplicate bug report (1228721).
> https://bugs.launchpad.net/bugs/1191447
>
> Title:
> Collection of design and experience issues with docs.openstack.org
>
> Status in OpenStack Manuals:
> Triaged
>
> Bug description:
> We still get disqus comments on very old doc pages (e.g., I replied to
> one today that was on a diablo(!) page).
>
> If we are going to keep these around, it would be helpful if they were
> clearly labelled as being out of date.
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/openstack-manuals/+bug/1191447/+subscriptions
>

This bug has not been fixed.

Hey Tom, what did you think of my last idea to get more detailed and then link those issues here?

In other words, can you triage this further to describe what will satisfy the criteria to close this bug?

Closing this bug fix-released, as the original bug report has been resolved. Conversation continues in a new bug (https://bugs.launchpad.net/openstack-manuals/+bug/1479166) to track the ongoing issues identifying old content in the new RST-based docs.

The original bug report was not resolved, changing to "Won't Fix"