Search problems in Ansible community/core docs

This issue highlighted a few search problems that I thought we should discuss.

The gist of the problem - currently all search goes to /latest/ docs. So if you are on core docs and search, you end up at /latest/. If you are on devel and search, you end up on latest.

The background - we moved to the SwiftType search engine a few years ago. Prior to that we had OpenSearch, which is what comes by default I think with the sphinx theme we were using back then? Anyway, I think the OpenSearch worked correctly, version to version. This predated the core/collection split but as I recall - an OpenSearch on 2.9 would stay on 2.9 so to speak.

We chose SwiftType for the fancy reports it could give us on what was being searched etc. Sadly that detail is currently limited to RedHatters (and frankly, only two or three of us). I don’t know enough about it to say if we could add a few DaWGs community members to it as well so it’s opened up a bit more. It does support faceted search, as you can see below (taken from controller docs that also use this search) -

As I recall, I looked into doing this for our Ansible core/package docs, but hit a roadblock. We use canonical URLs to point search engines to our latest docs so people searching external to our site won’t end up on Ansible 2.5 etc. Swiftype also obeys canonical urls so if we want to use this Swiftype engine AND faceted search, we’d have to drop canonical URLs.

Impact of dropping canonical urls

We could likely continue to publish the most recent Ansible package docs to the /latest/ url and still remove canonical urls from our docs. Given that we don’t publicize that people can find docs based on Ansible package versions, that might not open up the same problems we had back in the 2.8-2.9 timeframe. That combined with removing all older (EOL) docs and moving them to an archive site might be ok. Hard to tell really but that’s a guess on my part. Most traffic goes to /latest/ not say core 2.14.

If we did that, we would also likely have to republish docs down to say 2.8 and our jenkins jobs might not support that so… would be difficult.

Other options
The other option that came to mind but I never implemented it - we could remove swifttype from all the current core docs and go back to OpenSearch. We could similarly remove it from the package devel docs. At that point, I think all searches would stay local to that version.
NOTE - when we move core docs to RTD, this problem goes away by itself, so the better approach here might be to wait until we have all active core docs on RTD. That then only leaves devel docs popping over to /latest/ if we don’t remove the switftype engine and add it back when the stable branch is created for the upcoming docs release.

Open to ideas/suggestions etc.

1 Like

At the DaWGs meeting we decided to try bringing devel back to OpenSeearch and test it on the staging site. The core search problems will ‘fix themselves’ soon enough with the move to RTD.

1 Like