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

Bug #1191447 reported by Lorin Hochstein
52
This bug affects 6 people
Affects Status Importance Assigned to Milestone
openstack-manuals
Critical
Unassigned

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.

Revision history for this message
Tom Fifield (fifieldt) wrote :

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.

Changed in openstack-manuals:
status: New → Confirmed
importance: Undecided → Critical
tags: added: doc-builds
Revision history for this message
Anne Gentle (annegentle) wrote :

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-

Revision history for this message
Tom Fifield (fifieldt) wrote :

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?

Revision history for this message
Anne Gentle (annegentle) wrote :

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.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to openstack-manuals (master)

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

Changed in openstack-manuals:
status: Confirmed → Fix Released
Tom Fifield (fifieldt)
Changed in openstack-manuals:
status: Fix Released → Confirmed
Revision history for this message
Anne Gentle (annegentle) wrote : Re: Clearly mark outdated doc pages

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

Changed in openstack-manuals:
assignee: nobody → Diane Fleming (diane-fleming)
assignee: Diane Fleming (diane-fleming) → nobody
Revision history for this message
Tom Fifield (fifieldt) wrote :
Revision history for this message
Tom Fifield (fifieldt) wrote :

Hmm, I was wrong actually. Damn.

Revision history for this message
Kevin Jackson (kevin-linuxservices) 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?)

Revision history for this message
Anne Gentle (annegentle) wrote : Re: [Bug 1191447] Re: Clearly mark outdated doc pages

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
>

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to openstack-manuals (master)

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

Changed in openstack-manuals:
assignee: nobody → Anne Gentle (annegentle)
status: Confirmed → In Progress
Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to openstack-manuals (master)

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

Revision history for this message
Anne Gentle (annegentle) wrote : Re: Clearly mark outdated doc pages

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?

Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to openstack-manuals (master)

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

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to openstack-manuals (master)

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

Revision history for this message
Tom Fifield (fifieldt) wrote : Re: Clearly mark outdated doc pages

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

Revision history for this message
Anne Gentle (annegentle) wrote :

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?

Revision history for this message
Tom Fifield (fifieldt) wrote :

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.

Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Revision history for this message
Summer Long (slong-g) wrote :

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'.

Revision history for this message
Anne Gentle (annegentle) wrote :

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.

Revision history for this message
Anne Gentle (annegentle) wrote :

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

Revision history for this message
Anne Gentle (annegentle) wrote :
Tom Fifield (fifieldt)
Changed in openstack-manuals:
milestone: none → icehouse
Revision history for this message
Lars Kellogg-Stedman (larsks) wrote :

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.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to openstack-manuals (master)

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

Anne Gentle (annegentle)
Changed in openstack-manuals:
assignee: Anne Gentle (annegentle) → nobody
status: In Progress → Confirmed
Revision history for this message
Tom Fifield (fifieldt) wrote : Re: Clearly mark outdated doc pages
Revision history for this message
Tom Fifield (fifieldt) wrote :
Revision history for this message
Anne Gentle (annegentle) wrote : Re: [Bug 1191447] Re: Clearly mark outdated doc pages

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
>

Tom Fifield (fifieldt)
Changed in openstack-manuals:
milestone: icehouse → juno
Revision history for this message
Tom Fifield (fifieldt) wrote : Re: Clearly mark outdated doc pages

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

Revision history for this message
David Cramer (david-thingbag) wrote :

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

Anne Gentle (annegentle)
Changed in openstack-manuals:
assignee: nobody → Anne Gentle (annegentle)
Revision history for this message
Andreas Jaeger (jaegerandi) wrote :

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

Tom Fifield (fifieldt)
Changed in openstack-manuals:
milestone: juno → kilo
Anne Gentle (annegentle)
Changed in openstack-manuals:
status: Confirmed → In Progress
Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Revision history for this message
Anne Gentle (annegentle) wrote :

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

Changed in openstack-manuals:
status: In Progress → Fix Released
Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Changed in openstack-manuals:
status: Fix Released → Triaged
milestone: kilo → liberty
Revision history for this message
Anne Gentle (annegentle) wrote :

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.

Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Revision history for this message
Tom Fifield (fifieldt) wrote :

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.

Revision history for this message
Anne Gentle (annegentle) wrote :

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.

Changed in openstack-manuals:
assignee: Anne Gentle (annegentle) → nobody
Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Revision history for this message
Tom Fifield (fifieldt) wrote :

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.

Revision history for this message
Anne Gentle (annegentle) wrote :

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?

Revision history for this message
Tom Fifield (fifieldt) wrote :
Revision history for this message
Tom Fifield (fifieldt) wrote :

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)

Anne Gentle (annegentle)
summary: - Clearly mark outdated doc pages
+ Collection of design and experience issues with docs.openstack.org
Revision history for this message
Lana (loquacity) wrote :

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?

Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Revision history for this message
Lana (loquacity) wrote :

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?

Revision history for this message
Tom Fifield (fifieldt) 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 :)

Revision history for this message
Anne Gentle (annegentle) wrote : Re: [Bug 1191447] Re: Collection of design and experience issues with docs.openstack.org

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
>

Lana (loquacity)
Changed in openstack-manuals:
status: Triaged → Fix Released
Revision history for this message
Tom Fifield (fifieldt) wrote :

This bug has not been fixed.

Changed in openstack-manuals:
status: Fix Released → Confirmed
Revision history for this message
Anne Gentle (annegentle) wrote :

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?

Revision history for this message
Lana (loquacity) wrote :

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.

Changed in openstack-manuals:
status: Confirmed → Fix Released
Revision history for this message
Tom Fifield (fifieldt) wrote :

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

Changed in openstack-manuals:
status: Fix Released → Won't Fix
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers