Archiving Ansible documentation for EOL versions

[samccann]

Summary

PROBLEM

Currently, users searching for Ansible docs with google find prominent links to old EOL versions of the docs (2.3, 2.4, etc). This gives users outdated information. We would rather they are directed to /latest/ docs from external search engines.

We need to balance this with the understanding that some users really are using very old Ansible releases and need to give them a way to find these specific releases.

PROPOSAL

Based on an analysis by our search expert, we propose the following:

For existing EOL releases

1. Republish EOL docs to an archive site (e.g. docs.ansible.com/archive/ansible/2.3).
2. Allow Google to index the main page (e.g. docs.ansible.com/archive/ansible/2.3/index.html) but noindex/nofollow all other pages (in .htaccess file for this release). This allows a user specifically searching 'ansible 2.3 docs' to find the main index page and navigate to the EOL docs for 2.3 from there.
3. Put in permanent 301 redirects from the EOL docs to latest (eg.docs.ansible.com/2.3/x to docs.ansible.com/latest).
4. Update the latest banner on each page to add a link to the new archive site for EOL docs..

For current releases

1. Use current processes to EOL the docs and update the EOL banner to say' this will be archived in x months).
2. After that time, archive the docs and put in permanent redirects, following the procedure above.

Feedback welcome on this proposal!

[acozine]

Is the solution here proportional to the problem? It seems like executing this would be a lot of work, and could mean disruption for users who intentionally want docs for older versions. How much of a problem is it when users hit old docs? Do we know how many users are looking for recent docs and get old ones by mistake?

[tremble]

Put in permanent 301 redirects from the EOL docs to latest (eg.docs.ansible.com/2.3/x to docs.ansible.com/latest).

It's not quite clear what you're suggesting here. But where equivalent docs exist (eg modules) if at all possible please redirect to the latest doc for the module people were trying to access. Getting bounced from a search result that's showing the information you wanted over to the generic landing page for the latest docs is frustrating and feels to me like a bait and switch con.

[samccann]

@tremble the goal will be to put redirects to where that content lives in the latest, yes. So the 2.3 get_url module will redirect to latest ansible.builtin.get_url for example. That said, I'll need help with this from community for sure as my htaccess skills are nonexistent.

[samccann]

@acozine agreed - this is a significant amount of work. Long term (say five years) I think it will be worth it as we'd have a process in place to consistently archive the EOL releases twice a year. Whether we have the people to get us there is a big question, yes. Time spent on this is time not spent on other docs priorities. See #81 for a draft of those priorities :-)

Once this is all in place, (just thinking out loud) the effort to archive would be:

1. Update the banner for the EOL release to say 'this release will be archived to docs.ansible.com/archive in one month`.
2. Publish the EOL docs to that archive site one month later (and change the banner to just say this is an EOL release).
3. Create redirects to redirect docs.ansible.com/ansible/x.y to docs.ansible.com/ansible/archive/x.y.

I 'think' that final redirect should be simple since nothing else changes but adding /archive/ into the url. It's all these older EOL releases that will be painful to get the redirects correct.

[samccann]

We are experimenting with redirects that use REFERRERs to choose whether or not to redirect - https://hackmd.io/0B7n-FUySF6MB3CQeaqUkA?view

[samccann]

Important releases have all be archived and our search results are improved. Thanks everyone!