redirect automation to redhat.com

[oraNod]

This PR redirects the old "automation.html" page in a consistent way with redirects to redhat.com urls on the community website: https://www.redhat.com/en/technologies/management/ansible

[samccann]

Thinking out loud on this one a moment. The existing page includes all the controller docs, all the translated controller docs, and the controller archive.

The new page has none of that.

So my thoughts -

1. Wait until internal Red Hat has finished their migration of current controller docs
2. Update the existing page to remove any duplicates from that migration (with links to the new location on redhat.com
3. Leave the rest of the page from now til eternity.. :-)

Joking aside, I don't see how we can get rid of this page at all. Controller users go to this page for different controller docs. Even when those current (and future) versions of the docs are on redhat.com, we'll still have all the active older releases here from this page. Plus the archive access.

Maybe I'm missing something here?

[samccann]

Okay getting a little closer to understanding. It's this page - https://docs.ansible.com/automation.html that would be redirected I'm still inclined to say redirecting to a marketing page is incorrect but maybe someone specifically asked for this?

[samccann]

So basically, we had the old page - https://docs.ansible.com/automation.html In a general sense, that was recreated as https://docs.ansible.com/platform.html

So this PR takes the old page and replaces with marketing. I'd rather it replaces with the AAP docs homepage on access.redhat.com.

The new page has a related PR change at https://github.com/ansible/docsite/pull/204.

[tvo318]

@samccann - to address your concerns:

• Wait until internal Red Hat has finished their migration of current controller docs
• Update the existing page to remove any duplicates from that migration (with links to the new location on redhat.com
• Leave the rest of the page from now til eternity.. :-)

I agree, this approach is much more gradual than just pulling the rug from your readers' feet.

Joking aside, I don't see how we can get rid of this page at all. Controller users go to this page for different controller docs. Even when those current (and future) versions of the docs are on redhat.com, we'll still have all the active older releases here from this page. Plus the archive access.

Yes, I thought these were staying, regardless of the migration. The migration to access.redthat.com begins to support 4.4 and later, and any customer with older versions of 4.4.7 and older will still have to access these pages as they normally would.

[tvo318]

It's this page - https://docs.ansible.com/automation.html that would be redirected I'm still inclined to say redirecting to a marketing page is incorrect but maybe someone specifically asked for this?

Doc-for-doc would make it easier for the transition than doc-to-marketing page.

[oraNod]

I think it's OK to wait until the shift to "redhat.com" is further along.

For reasons, I don't think we can update the automation.html page. It's pretty much hidden on "docs.ansible.com" with no direct links in the navigation. So we either redirect or just let it sit there for eternity. I mean we can do something like ssh to the server and manually edit with vi. It's just an html file.

Redirecting seems like the way to go because those "latest" urls in the doc links won't actually be the most up to date version when 4.5 comes along. Redirecting is also good because whoever might still be using it is likely to have it bookmarked. And I'd put money on most of those folks being Red Hatters.

Please refer to my comment in the related PR for the platform page as to why the "marketing" url is preferable: https://github.com/ansible/docsite/pull/204#issuecomment-1842623534

I would also add that this redirect is permanent and a doc to doc redirect is more likely to break SEO. Not only that, creating this redirect helps that marketing link gain "authority" in terms of SEO and helps direct RH customers to the correct entry point for the platform.

[samccann]

Going to throw some stats here so we can use them to help us out a bit in this discussion. These are from Sept 1 2023 - Dec 6 2023 and are unique visitors:

docs.ansible.com page - 68.3K docs.ansible.com/ansible-tower - 8K (old page not linked to from anywhere so likely bookmarked/blog posts etc) docs.ansible.com/automation - 4.7k (old page not linked to from anywhere so likely bookmared/blog posts etc) docs.ansible.com/core - 4.7k docs.ansible.com/ecosystem - 3.4K docs.ansible.com/users - 3.2k docs.ansible.com/developers - 2.6K docs.ansible.com/platform - 1.5K

[samccann]

Thinking about the stats above, I see two things:

1 - people are clinging to older pages. This is not good as we don't maintain them anymore.

2. More people are going to both 'tower/controller' older pages so changes here will impact the most readers.

I'm going to think outloud here. What if we redirected both those older pages to the new /platform page instead? This has the benefit of taking a bunch of bookmarked pages and shifting them to the newer/updated platform page. A quick scan says the current platform page has equivalent information for now. The drawback? As @oraNod mentioned in the other related PR, it still leaves customers thinking this is the place they should be for controller docs, and while that is true today, it won't be true 'soonish'. We could remedy this with a banner or clear indication on the /platform page that this content is moving to the AAP page in the near future so they hopefully bookmark both pages.

We update the platform page first, when all the controller docs are on access.redhat.com This has the benefit of waiting until we are in our 'final state' so to speak - where current and future controller readers all need to go to access.redhat.com for information. In the interim, we update the two older controller/tower pages with a big ugly banner to say 'you are on the wrong page and we will remove this soon' Which gives them lets say a month to realize and start bookmarking the new page. Then at the end of Jan 2024, we redirect both old pages to 'some url'

I say some url because I still don't feel the marketing url is the correct place. To me, this is the correct url - https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform

It will automagically go to the most recent AAP docs, where there is a left-hand filter option for controller docs. It's not a direct doc link to each controller guide, so not ideal, but I think solves some of the worries about our community page links to Red Hat getting stale over time.

But in general, after reviewing stats and reading comments in the other PR, I'm still against a hard redirect from this page (and the older tower page) directly to a marketing page. It's too jarring, the wrong content, and impacts something like 4K visitors a month. That's a lot of people to give a less-than-ideal experience. I would much prefer we redirect both to the current platform page, then do not update that page until all the controller docs that are moving are on access.redhat.com.

Also, @tvo318 - I thought the API docs have no current plan to move (and maybe the CLI guide as well). If that's correct, we have a long-term need for a controller home on docs.ansible.com

[oraNod]

The API reference is incorporated into the AWX docs and the CLI will be included there too (in the new year).

[oraNod]

TL;DR for redirecting "automation.html" to https://www.redhat.com/en/technologies/management/ansible

Pros:

• Creates a consistent path/experience between the "docs.ansible.com" subdomain and "ansible.com" (after the community website launches)
• Defines a single entry point for the platform across the community site.
• Relieves the Ansible community of the burden of maintaining downstream urls - for example if "access.redhat" changes to "docs.redhat"
• Reinforces the desired outcome of Red Hat customers accessing product documentation and platform content from "redhat.com" rather than the community site.
• Makes it possible for Red Hat to improve and control the user experience and discoverability of content separately from the Ansible community.
• Helps establish SEO authority to the target page with a permanent redirect.
• Eliminates redundancy on "docs.ansible.com". That page is not needed in addition to "platform.html".
• Points to the correct location for "latest" controller documentation. Automation controller documentation is now available from the Red Hat documentation site. When controller 4.5 GAs the latest version will only be available from the Red Hat documentation site. Any "docs.ansible.com/automation-controller/latest" urls will no longer be valid and have content for the previous version.

Cons:

• Even though there is prominent "Documentation" link on the target page it results in extra hops to find downstream content. Red Hat customers will need to do a bit more work as the flip side to lowering cost of maintenance on the "docs.ansible.com" subdomain for the community.
• Platform content on the "docs.ansible.com" subdomain still gets a relatively high number of visitors and page views. It might be the case that the page is bookmarked and used as the entry point to automation controller documentation. Redirecting those pages could make it harder for RH customers to find content for previously supported versions. They would need to return to "docs.ansible.com/platform.html".

[oraNod]

@samccann Thanks for the reminder about "docs.ansible.com/ansible-tower". That's actually the page that we need to remote into the web server to do anything about. Now that I recall it just needs to stay put until the 3.8 whatever release version goes EOL. I think that is the only resource for that version so we just need to let it be.

As for redirecting "automation.html" to "platform.html" - that could work because both pages serve the same purpose and it removes the duplication without adding extra hops. When controller 4.5 ships then I think that will leave RH customers stuck without a link to the actual "latest" version of the documentation.

It also means "docs.ansible.com/platform.html" builds more SEO authority than the "redhat.com" site.

Further down the line when 4.4 eventually goes EOL we'll probably want to get rid of "platform.html". If a redirect is the answer to how we do that then we'd probably want to change any redirects from "automation.html" to "platform.html".

Let's see if we can get some more input from folks on the direction we want to go. Thanks for digging up those stats and providing all the detailed comments! :+1:

[samccann]

so +1 for redirecting automation to platform. Do we need anyone else to pipe in here or can we jus do that?

[oraNod]

@samccann I think we can just do that. I'll update the PR and you can merge whenever.

As for my previous comment about what happens when we get to the point where "platform.html" is no longer needed... I guess we could just leave it there as a "ghost" page or whatever without redirecting it. That way we won't have a redirect that points to a page that is also redirected. I'm not actually sure if a redirect chain would work.

That would be the only issue here that I can see, if there is some future decision to redirect "platform.html".

[tvo318]

As for redirecting "automation.html" to "platform.html" - that could work because both pages serve the same purpose and it removes the duplication without adding extra hops. When controller 4.5 ships then I think that will leave RH customers stuck without a link to the actual "latest" version of the documentation.

4.5 was released about a week after this comment was made; so customers now have a link to the actual "latest" version of the documentation.

[tvo318]

Instead of redirecting, could we just update the page to state, "This page will be removed in a future release. For official docs, go to access.redhat.com"; for previously supported versions of the docs, Visit the archive."

I believe it's the case that we can't update the automation.html page.

[oraNod]

@samccann and @tvo318 I've changed this so automation.html redirects to platform.html. Thanks for all the discussion!