# Swiftype search evaluation for docs.ansible.com

- [Swiftype search evaluation for docs.ansible.com](#swiftype-search-evaluation-for-docsansiblecom)
* [Status](#status)
* [community comments](#community-comments)
* [What's going wrong](#what-s-going-wrong)
* [Prior changes](#prior-changes)
* [Weighting changes (Aug 16 2021)](#weighting-changes--aug-16-2021-)
- [Next Steps](#next-steps)
* [Play with rankings](#play-with-rankings)
* [Adding faceted search to differentiate collections from general guides](#adding-faceted-search-to-differentiate-collections-from-general-guides)
+ [How to add a facet type for modules vs guides](#how-to-add-a-facet--type-for-modules-vs-guides)

<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>

## Status
Swiftype is the search engine used 'under the covers' for the docs.ansible.com/ansible searches. Current problems include:
* All searches go to /latest/ for search results. Tower docs solved this by turing on 'facets' to select the version the user wants to filter results to. Ansible cannot do this without losing the canonical URL configuration we use to drive traffic to /latest/.
* Search results tend to be useless. This may be because the user is either looking for a module, and gets a bunch of other stuff, or is looking for other stuff, and gets a bunch of modules instead.

## community comments
https://github.com/ansible/ansible/issues/72106
https://www.gitmemory.com/issue/ansible/ansible/72112/704356745

## What's going wrong

After testing a few search results, it seems the search engine isn't using the most popular pages.

A search for 'netcommon' doesn't report the netcommon collection index page, but reports 'ipaddr' as the top hit as that is significanly more website hits (2.7K) in a month vs the netcommon index page (at just under 1k hits). This doesn't explain why netcommon index page isn't the second hit. Instead, it is a module within the netcommon collection, which has less hits than the ntcommon index page based on adobe web analytics for the past month.

Similarly a search for `file` reports two top results which web analytics puts as 200 or so hits, and the third result is `ansible.builtin.file` which web analytics has as 34 THOUSAND hits.

## Prior changes

[This PR](https://github.com/ansible/ansible/pull/65574/files) added the version metadata to all files. This should allow us to enable faceted search based on version but it collides with our use of cannonical URLs. Basically, since we want all google hits etc to use /latest/, we set that as our canonical url in the conf.py files. This means swiftype is only searching latest and as such, faceted search based on version will not work for swiftype.

We could use something similar to mark static RST files as 'guides' and autogenerated collection docs as 'collections' or 'modules'.

## Weighting changes (Aug 16 2021)
The existing 'weighting' for search results favored the body of the page over title or popularity. We changed this today so that should improve search somewhat.

# Next Steps

## Play with rankings
We have the ability to set higher priority results for search terms that aren't behaving (cough `command` lookin at you!).

## Adding faceted search to differentiate collections from general guides

This link will only work for someone with access to the swiftype engine (aka internal to Red Hat), but since it seems impossible to find via navigating swiftype, I'm putting it here cuz it took me an hour to find it again - https://app.swiftype.com/engines/ansible-core/interface_designer

Which would result in something like:

Where we would define the type in the metadata.

### How to add a facet type for modules vs guides

The html that needs to be injected is fairly straightforward. Something like:

<meta class="swiftype" name="type" data-type="string" content="{{ plugin_or_guide }}">

The tricky part is where/how to inject this. Our current metadata (version) applies to all HTML pages and is a customization to the sphinx Ansible theme. For choosing between modules/plugins and guides, we would have to find another way to inject this html during the build.

###### tags: `todo` findability` `Documentation`