[DONOTMERGE] adds search #109
Conversation
|
There are a few issues with the search right now which I've fed back to the developers. One is captured here: alphagov/tech-docs-template#166 ☝️ I've tested a fix for this locally and I'm satisfied it's been solved. One, more serious, problem is that (and you can confirm this in the test environment at https://registers-docs-testing-2.cloudapps.digital/) currently searching for certain things like 'Get' doesn't produce the intended outcome. The developers at Convivio are currently working on it and it's at least partly because of stop words, see alphagov/tech-docs-gem#38 The test environment currently has a test fix though and whilst searching 'Get' (which was one of the stop words) no longer produces 0 results, it doesn't produce expected results in that it doesn't show any of the endpoints. Same goes for searching for e.g. 'Linked'. For the purposes of this PR, I think we should hold off before merging. We could still go with it as it stands as it is still technically functional, though: I will leave it up to you guys @gidsg @michaelabenyohai @arnau @MatMoore |
|
The fix to the first issue I mention above is also fixed in https://registers-docs-testing-2.cloudapps.digital/#gov-uk-registers-quick-start-guide |
|
The results look a bit dodgy to me too. If I copy a description from one of them like "Get information about a register" or "Get all records from a register" that page doesn't show up in the results. The snippet on the results page sometimes looks strange as well, for example if I search for country it shows me the quick start guide with "… //country … country … //country … //country … //country …" Do you know if the queries are currently being sent to GA so we can monitor what users actually search for? We don't need it to be perfect to put something live, but we should be able to get some usage data so we can prioritise improvements. |
|
I don't think we have any GA for the test environment(s) but we do for the live environment, though I guess @michaelabenyohai would need to set it up for this search specifically if we merge this PR? Having spoken to Convivio it seems like lunr is not returning the API reference pages as results in at least some cases. If you try searching "Linked" though, for example, it does return some 🤔 |
|
Ah this is the PR that will add GA tracking: alphagov/tech-docs-gem#39 so it's not there yet, but we'll have it eventually. |
|
Not sure what can be done here but results like this one make me wonder if we would be better with a list of links (no excerpt) or with the first paragraph.
|
Edit: I was testing in my local instance without the unstable changes that are included in the test environment but not in this PR. The test environment works as expected 👍 |
I'm not too bothered by this. A result list for the search “get” is not that useful. Even a search like “get entries” gives me lots of results for “get” which are not relevant to me. That said, “get + entries” works as I would expect. I guess I want it all :D so probably I would like “get“ to be relevant only when it is in an AND operation. In any case, I rather not have results for “get”. |
|
I guess that the best solution for the tech docs gem would be to allow stop-word customisation so we can tune it based on our needs. |
|
Another surprising search is “json”. Do we truly only have two pages with “json” in it? |
|
@arnau we can talk about the first comment you raised separately if that's OK? re. the fix not showing for you with the search box not closing on submenus, I really don't know: it seems to be fixed for me locally and on that test version based on what testing I've done with different combinations ... what are you searching for/where are you when you initiate the search? The problem re. "Get" is ....... with what user research I was able to do on the Pay docs specifically (i.e. not just user research on the format itself) both participants tried to search "Get" and were unsuccessful. I realise that's a limited sample and for the record neither were developers, but nevertheless it's a little concerning. A key difference is the Pay docs are much more wide-ranging and are intended for more users than just developers. We should be able to have stop-word customisation, yes. re. the "json" search, no; it should definitely show more than that. |
|
It seems that the term 'application/json' returns the results you'd also expect from 'json'. It's not clear why, but maybe I can add some additional tweaks here to include 'application/json' when searching for 'json' I've found a fix for the 'get' issue. I've had to make some modifications to the middleman-search gem, once I can get them merged then you can test it. Per-docs stop word customisation and other customisation options are possible. I'd rather we start trying to get a good default built into the gem first and then add custom options later. |
|
I'd also rather we had good defaults in the gem. Any project specific customisations will be a pain to manage over time. |
|
I've created an issue in the lunr.js repo to see if I can get any pointers: olivernn/lunr.js#365 |
|
We should try this again with the new version of the gem. There are still issues with it but I think it's working better than when we first tested this. If it's still not good enough to use, I can potentially do some work on it to make title matches appear higher in the ranking. |
Context
Adds a search bar to the tech docs
Changes proposed in this pull request
Relevant changes to the config files, the rest should be picked up by the build/deploy
Guidance to review
Testable at https://registers-docs-testing-2.cloudapps.digital/