Adding direct links to older/newer versions

[dagwieers]

ISSUE TYPE

• Documentation Report

COMPONENT NAME

Documentation

ANSIBLE VERSION

v2.5

SUMMARY

So I really think we need to do a better job in allowing users to move from the existing versioned docs, to the latest stable, and the latest development version of the docs.

Currently there is a single link to a page that at the very bottom has a drop-down menu which brings you to the main page of that versioned documentation and leaves it up to the user to find the relevant page for the latest stable/development version. That is a very poor user experience.

What we should do instead, and what is not that hard to achieve, is have a link for every page that brings you to the relevant latest stable and development page, directly. We can do this easily thanks to the existing redirects already in place. But not in all directions, going backwards, newer locations have no redirects to older pages, but it's not an impossible thing to fix.

And a proper error-page could still bring you to the main index or search page if we did not find a match. At least that is a much better user experience than the current.

[ansibot]

Files identified in the description:
None

If these files are inaccurate, please update the component name section of the description or use the !component bot command.

click here for bot help

[docschick]

@dagwieers interesting ideas here. Could this be brought up in an IRC meeting for further discussion? @dharmabumstead -- let's explore this more as anything and everything we can do to improve the user experience is good in my eyes.

[dagwieers]

@docschick After a discussion with @gundalow on IRC it was clear that this is too late for v2.5 release, but we can still do it in a few weeks and backport the relevant changes.

[gundalow]

Removing from 2.5.0 milestone & project as this isn't a blocker for 2.5.0

[skylerbunny]

If we do this, I would further suggest that the 'Edit on GitHub' link at the top of any given documentation page lead to the version specific branch of that file, not the devel branch of it (which it does for ALL versions currently). Someone who clicks that link from a 2.4 page expecting to fix a 2.4 documentation error would be very surprised to find themselves on the 2.6 docs.

[bcoca]

i'm fine with removing the link, at least from the non devel versions.

[gundalow]

It's by design that Edits go to devel and then the PR get's backported as needed.

[dagwieers]

I would like to get back to this. I think we can achieve this by changing the mechanism.

• If we would drop a small static JSON file in the devel tree that lists the supported versions, stable and devel
• Every page would then show this somewhere at the top:
  • Versions: 2.4, 2.5, 2.6, 2.7 (stable) and 2.8 (devel)
• This would still work for older versions of the documentation, since they all source this static JSON file from the devel tree (this allows to have this update in one tree only)
• If a page was relocated, we would need to add 301 Permanent redirect in both directions (so only if the file was not found a redirect attempt would be performed).
• If a page does not exist, we would give a generic error explaining that the document likely did not exist at this location. Based on the http_referer you can tell if the user came from a different version, so the error could be very specific.
• The current Not Found could be made much better to guide users back to the documentation, instead of the current dry 404 Not Found message.

PS If we can test in Javascript if links exist, we can make this smarter. But I don't want to add complexity at all cost, the above would already be a great improvement to help guide people to the best/latest documentation.

[acozine]

@dagwieers this is a great idea, but not a priority in the runup to AnsibleFest. This is something I'd like to discuss in Austin, though.

[acozine]

Closed by #55655 (and related backports).