Sunset EOL versions of the docs

[debadair]

It's helpful for folks to be able to reference docs for older versions, but we want to steer people who are new to the stack to the latest versions and encourage people who are running EOL versions to upgrade.

To this end, we should:

• Omit EOL versions from the version drop-down.
• Update the banner on EOL versions to highlight that it is EOL, encourage upgrades, and direct folks to documentation for the latest version.
• Add noindex tags to EOL versions.
• Submit a reindex request to Google.

We should start with the 1.x series and monitor the SEO and traffic impacts as we sunset and remove each version. (Suddenly dropping thousands of pages from Google's search index could have unexpected/undesirable consequences.)

At some future date, we might opt to stop publishing the oldest versions entirely. These are basically the prerequisite steps to doing that.

Why keep the oldest versions around at all?
Historical interest. To preserve information about upgrading for folks running really old versions.

How does this encourage people to upgrade?
It lends some urgency to making a change if users see us phasing out documentation for older versions. Updating the banners will reinforce when versions reach EOL.

How does this help steer users to the latest version?
Not having those versions show up in search results should boost the signal of the more recent versions a bit. Making it clearer when you've landed on an EOL version should also help people realize there's more-recent content.

Depends on: #1324, #1431, #1426

[lcawl]

I had thought at the very least we should stop updating and building the out of support versions (i.e. leave a static copy of that content on the web). If we can get away with removing them entirely, however, that's even better.

[debadair]

Having fewer duplicate pages has benefits from an SEO perspective, and reduces the likelihood of unsuspecting users landing on pages that don't apply to the version they're using.

As part of the migration effort, @nik9000 raised a concern about publishing pages that we can't update. If we simply freeze them and stop routinely building them, we are likely to break the ability to build them without knowing it. If we're still publishing them, that leaves us exposed if some issue crops up that affects those pages.

[zuketo]

I completely agree with:

• Discontinue publishing EOL versions of the docs except for the last minor in the major version series. Today, for ES that would mean publishing: 0.90, 1.7, 2.4, 5.6, 6.3, 6.4, 6.5, 6.6, 6.7, 6.8, 7.0, 7.1, 7.2, 7.3, 7.4, 7.5, 7.x, master.
• Update the banner on the remaining EOL versions to highlight that it is EOL, encourage upgrades, and direct folks to documentation for the latest version.

I'm not sure about removing old versions, I need to compile more data here (e.g. user count by version). It sounds that removing old versions from docs has two main benefits:

• SEO
• User confusion (e.g. landing on an old page)

Could we keep unmaintained versions around but place them somewhere else, so they don't show up in the version drop down and aren't weighted equally by search engines? I believe that would help with the two benefits described above.

For instance, /guide/en/elasticsearch/reference/6.0/index.html and /guide/en/elasticsearch/reference/6.8/index.html are similar in URL structure, however, if 6.0 contained 1-2 more subdirs, I believe that should be enough to push it down in results (e.g. /guide/en/elasticsearch/reference/archive/versions/6.0/index.html)

[debadair]

We could just sunset the old versions by updating the banners and adding the noindex tag, but continue to build and publish them. @nik9000 how difficult it would be to only show the "live" versions in the drop down? That seems like it might not be a hard change?

Changing the URL structure seems likely to cause a lot of the same link problems as removing the pages, without the global redirect hammer to minimize the disruption. But if they're marked noindex, they aren't going to show up in results.

[nik9000]

I think it'd be pretty easy to only show the live versions in the drop down.

…

On Mon, Nov 18, 2019, 19:37 debadair ***@***.***> wrote: We could just sunset the old versions by updating the banners and adding the noindex tag, but continue to build and publish them. @nik9000 <https://github.com/nik9000> how difficult it would be to only show the "live" versions in the drop down? That seems like it might not be a hard change? Changing the URL structure seems likely to cause a lot of the same link problems as removing the pages, without the global redirect hammer to minimize the disruption. But if they're marked noindex, they aren't going to show up in results. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1419?email_source=notifications&email_token=AABUXIXXVXECJHLUKFHNRMDQUMYMRA5CNFSM4JOC6VW2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEEMNRJI#issuecomment-555276453>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABUXIRJU4WJLQXKGW3ZI7TQUMYMRANCNFSM4JOC6VWQ> .

[zuketo]

@debadair nice solution, and reducing the size of the drop down list will make it easier to navigate

Yea, scratch the url structure suggestion :)

[bmorelli25]

I really like this proposal! Quick question:

When we say documentation is no longer being updated, like in elastic/stack-docs#694, does that simply mean that we're not backporting to these branches? Or is it broader than that? For example, how does link checking fit into this conversation? If we're not backporting, should we also consider turning off link checking in our builds for these branches?

[lucabelluccini]

Hello @debadair ,

We're collecting some feedback from Support:

• Mangling the URL takes generally more time
• The previous version selector "tried" to maintain you on the same page/section, while now it points you to the documentation index
• It seems strange though that what we consider "outdated" versions from docs does not match our EOL policy. I get that we want to encourage users to upgrade to the latest version. But I am not convinced that simply hiding the older (non-EOL) versions will do the job. There are many reasons why customers are not moving as fast as our releases and the top reasons are not because of accessibility to documentation that matches the versions they are currently running
• From a customer: "why you display out of date on 7.3 docs". There's no mention of "Out of Date" in our documents, but only end of life or end of maintenance.
• https://github.com/elastic/website-www.elastic.co/issues/5151

Those are our thoughts at the moment:

1. Only EOL versions should be removed from the drop down
2. All versions should be retained and indexed so we can search them (at least within our website)
3. The "other version" selector should bring up the page that was open (if it exists in that version)

Those are just ideas and we would like to discuss about it.

CC @elastic/janitors @elastic/support-tech-leads

[nik9000]

Only EOL versions should be removed from the drop down

This is something the writers will have to manage.

All versions should be retained and indexed so we can search them (at least within our website)

I believe they still are, though we might have made it more difficult to get at them. I'm not sure. @debadair, do you know who manages the search stuff? I'd be happy to talk to them.

The "other version" selector should bring up the page that was open (if it exists in that version)

I'll work on that now.

[debadair]

@lucabelluccini Thanks for the feedback!

@nik9000's proposal in #1538 feels like a good compromise wrt the drop down. It's an extra click from the original behavior, but the end result is the same.

One of the motivations for these changes was to make the end of maintenance and EOL policy more apparent in the docs. There is no change to what's considered OOM and EOL--the difference is actually that we're being more consistent with that policy and only updating docs for OOM versions in exceptional cases.

I've opened a PR to tweak the notice for out of maintenance versions to be a little less alarming:

No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
current release documentation.

I think there was (for a short bit) an "out of date" label in the drop down. I agree that wording is less than ideal & we'd rather not have a bunch of qualifiers cluttering the drop down.

We'll need to dig in to the site search options a bit more. We want to set noindex on the EOL versions so Google quits driving so much traffic to EOL versions. Most of the traffic is to getting started type content and general topics like the query DSL--topics where folks are much better served by the latest content. As things stand, I believe noindex also causes our site search to skip those versions--which probably is still reasonable for EOL versions. (One of the issues with our site search is that we're surfacing old versions over new ones when no version is specified.) That said, I think we might have ended up treating EOL & OOM versions the same, and that probably isn't what we want.

[nik9000]

I think there was (for a short bit) an "out of date" label in the drop down. I agree that wording is less than ideal & we'd rather not have a bunch of qualifiers cluttering the drop down.

It shows up if you go to a version that isn't "live". I'd be quite happy to change the label.

[nik9000]

The "other version" selector should bring up the page that was open (if it exists in that version)

I'll work on that now.

I've merged #1538 which feels like it'll make things a little better.

[debadair]

It shows up if you go to a version that isn't "live". I'd be quite happy to change the label.

Instead of changing the "out of date" label in the drop-down, maybe just remove it? With the banner, I don't think it's necessary.

[nik9000]

Instead of changing the "out of date" label in the drop-down, maybe just remove it? With the banner, I don't think it's necessary.

I opened #1546

[shanksy01]

Folks, we need the EOL docs to absolutely be searchable by at least support - has this been blocked already and if so, can it be reverted or can we have instructions on how to do it internally at least please?
@elastic/support-tech-leads
@elastic/janitors

[nik9000]

Folks, we need the EOL docs to absolutely be searchable by at least support - has this been blocked already and if so, can it be reverted or can we have instructions on how to do it internally at least please?

I thought they were still showing up but, just like you say, they are all gone now. I'll see what I can do about it.

[nik9000]

I've opened #1590 which should get the pages back into the docs sitesearch. I'm not sure how long that takes. I'm trying to find someone to help me access the sitesearch instance we use so I can change things.

[nik9000]

Page are now starting to show up for the old versions of the docs again.

[nik9000]

@debadair, I think you'll want to have a look at the search when you get a chance. I think we'll probably want to tweak it to make the old versions less prominent. Or something. But keep them accessible.

[debadair]

The changes have been live for some time & support seems satisfied with the ability to access the drop downs.

Tuning search results is a separate issue.