15:00:55 <acozine> #startmeeting Documentation Working Group
15:00:55 <zodbot> Meeting started Tue May 28 15:00:55 2019 UTC.
15:00:55 <zodbot> This meeting is logged and archived in a public location.
15:00:55 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:55 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:55 <zodbot> The meeting name has been set to 'documentation_working_group'
15:01:13 <acozine> who's around today?
15:01:59 <acozine> #chair samccann mrproper
15:01:59 <zodbot> Current chairs: acozine mrproper samccann
15:02:04 <acozine> anybody else?
15:03:16 <samccann> here!
15:03:41 <acozine> yay!
15:04:46 <acozine> dag: I merged your botmeta update this morning - if you don't want people to have to confirm on GitHub before we add them to the botmeta, can you paste a link to the core meeting minutes where the folks volunteered?
15:05:08 <acozine> I'd like to check for typos in the user names, if nothing else
15:05:24 <dag> acozine: They volunteerded in the community wiki
15:06:22 <acozine> ah, excellent, if you could add a pointer from the PR to the wiki, that would be great
15:06:55 <acozine> (the next PR, that is)
15:07:55 <acozine> for reference, for anyone else who's wondering what the heck dag and I are talking about, see https://github.com/ansible/ansible/pull/57053 and https://github.com/ansible/ansible/pull/56816
15:08:25 <acozine> #topic update on the version-switcher
15:08:47 <acozine> samccann has the version-switcher working, and the last blocker is the improved 404 page
15:09:28 <acozine> https://github.com/ansible/ansible/issues/51439
15:10:26 <acozine> I ran into issues trying to use the sphinx-notfound-page project, and the authors have been very responsive, but I haven't followed up on that yet today
15:10:56 <samccann> sounds like progress to me!
15:11:31 <acozine> yeah, I think it will work, and we might help that project reach a 1.0 release in the process
15:12:34 <acozine> #topic last call for AnsibleFest proposals
15:13:04 <acozine> today is the deadline for proposing a talk for AnsibleFest 2019
15:13:06 <acozine> https://ansiblefest2019.eventpoint.com/cfp
15:14:07 <acozine> I'd love to see folks who are interested in documentation in Atlanta, so please propose a talk (on docs, or on any other subject)!
15:14:49 <acozine> The contributor summit will take place on Monday, the day before the main conference
15:15:07 <acozine> and we'll have a hacker space called Contributor Central during the conference itself as well
15:15:58 <acozine> #open floor
15:16:04 <acozine> heh, oops
15:16:08 <acozine> #topic open floor
15:16:21 <acozine> mrproper: do you want to talk about search for the docsite?
15:17:13 <samccann> is this search in general, or the two search options we currently have?
15:17:36 <acozine> we were chatting about search before the meeting started
15:17:59 <acozine> how to improve it, can we allow searches of just the dev guide pages, for example
15:18:28 <acozine> and how most people don't realize there are two search options on the site
15:19:06 * samccann reads back
15:19:19 <acozine> just like the Sphinx styles, i think we need to get rid of the second search option before we start optimizing
15:19:36 <samccann> ah ok.  Yeah the two searches... I'm thinking the top one might have come with the sphinx rtd theme.  at least it shows up as part of it
15:19:49 <acozine> oh, interesting
15:20:08 <acozine> I thought maybe someone added it because they didn't see the Swiftype search
15:20:08 <samccann> I can experiment if you want, but then will we have the problem that people don't find that other search in the lower left corner?
15:20:44 <acozine> yeah, probably the first step is to figure out what we want in a search facility
15:21:09 <acozine> and I suspect that "it shows up in the usual top-left position" is high on that list
15:21:32 <samccann> heh
15:22:20 <samccann> so basically you want the functionality of the lower-right search because it give a report and can help us optimize based on what folks search for.. .but have that search show up in the upper left?
15:22:27 <acozine> it's certainly possible that the swiftype search can be moved there, though I don't know if we can control the placement on a per-project basis (i.e. can it show up upper left on docs.ansible.com/ansible and lower right on docs.ansible.com/tower?)
15:22:43 <samccann> ah yeah that could be a gotcha
15:22:46 <acozine> samccann: if that's possible, it would be great
15:23:13 <acozine> there also may be other things I haven't thought of that we want from the search capability
15:23:27 <acozine> I don't use the search much, since I know the docs pretty well
15:23:46 <samccann> i admit to using it regularly but the upper-left one :_P
15:24:54 <acozine> back in the fall, I opened https://github.com/ansible/ansible/issues/45939 with the information I had at the time
15:25:06 <acozine> haven't done much with it since . . .
15:26:11 <acozine> #info please add comments, ideas, questions about searching the Ansible documentation to https://github.com/ansible/ansible/issues/45939
15:26:22 <mrproper> acozine: I was away from my desk, sorry!
15:26:28 <acozine> mrproper: np
15:28:31 <acozine> maybe we should do some comparison testing of the results of the two search options?
15:28:53 <mrproper> I was going to ask, do they use the same engine?
15:28:55 <acozine> when I have used the search, I haven't found the results very useful
15:29:05 <mrproper> Me either. Results are pretty rough.
15:29:23 <samccann> they seem to return different result
15:29:27 <mrproper> Partially because the results don't show previews, only the title for the article. So if there's 40 articles, I lack context.
15:29:47 <acozine> mrproper: one is Swiftype, the other is Opensearch - I'm not entirely sure of the differences
15:30:20 <acozine> see issue 45939 (linked above) for some pointers
15:32:02 <acozine> can I post screenshots here?
15:32:21 <mrproper> I'm fine with it.
15:32:28 <acozine> https://usercontent.irccloud-cdn.com/file/al3b0e8v/Tower%20Swiftype%20search%20results
15:32:51 <acozine> so that's what the Tower swiftype results look like
15:33:23 <mrproper> I like that it lets you specify version info.,
15:33:43 <acozine> yeah, that's useful
15:33:52 <acozine> here's the same search on the ansible/ansible docs
15:34:10 <acozine> https://usercontent.irccloud-cdn.com/file/faS8cpkD/Swiftype%20search%20on%20ansible%20core%20docs
15:34:23 <acozine> it gives a little context . . .
15:34:44 <acozine> more, at least, than the opensearch results do
15:34:46 <mrproper> The context itself isn't overly helpful.
15:35:16 <acozine> no, it isn't
15:35:29 <acozine> but it's marginally better than that same search in the current opensearch box:
15:35:38 <samccann> it could be a case of understanding what it's trying to pull in for context, and then optimizing that in the docs
15:35:42 <acozine> https://usercontent.irccloud-cdn.com/file/roDzqysU/Opensearch%20results%20for%20%22roles%22
15:36:08 * mrproper thumbs down Opensearch
15:36:44 <acozine> I think both options are currently set up as "bare bones", and probably either one could be made much better
15:36:45 <samccann> my 'nickel' is it could be fairly easy to get read of that search... harder to figure out how to the the other search to show up in the upper left
15:37:14 <acozine> yeah, some research is definitely indicated
15:38:21 <acozine> does anyone know of a docs site that does search really well?
15:38:52 <acozine> maybe we can copy an existing solution
15:39:07 <mrproper> I've had decent luck with the AWS one.
15:39:11 <mrproper> Good luck copying that one though.
15:39:22 <acozine> and/or does anyone know what either opensearch or swiftype uses for indexing behind the scenes?
15:40:13 <acozine> mrproper: yeah, we probably can't copy the AWS search . . . highly unlikely that there's anything open-source about it
15:41:53 <samccann> search within a docsite is always problematic... no one can keep up w/ the search engine world (aka google etc). So it always feels like a step down
15:42:02 <acozine> samccann: I believe we pay a subscription for the swiftype results, so they may have support available
15:42:03 <samccann> that said, we can likely make the ansible searches better
15:42:35 <acozine> I'd settle for a step down . . . right now it feels like a couple of flights of stairs down
15:42:42 <samccann> lol
15:44:18 <acozine> there must be a way to weight headers more heavily than the sheer number of times a word shows up on a page
15:44:41 <acozine> and maybe a way to include snippets of text in the search results too
15:46:46 <acozine> here's something we could try:
15:47:26 <acozine> come up with a few search terms that currently don't return the material we want users to find
15:47:41 <acozine> and use those as a benchmark for "is the search better now"
15:48:11 <mrproper> Do we know of search terms which that applies to?
15:48:42 <mrproper> I think we should also use common and good search terms to make sure there aren't easy to spot regressions.
15:49:49 <acozine> mrproper: I don't; like I said, I don't actually use the search much, though when I do use it, I generally think, "hm, that's not gettin me the page i had in mind"
15:50:08 <acozine> that said, I don't think I'm a good example of "the usual Ansible user"
15:50:44 <acozine> so it could be that the results themselves are okay, and it's just the UX that needs work
15:51:12 <mrproper> Me either. I wonder if people in #ansible could offer guidance there.
15:51:16 <samccann> if you have the swiftype search results each week, we could look for common searches
15:51:43 <acozine> good idea
15:51:49 <acozine> here are yesterday's results
15:52:05 * mrproper is going to start sending messages via the search results. "Hey acozine!"
15:52:13 <acozine> heh
15:52:13 <samccann> AAAAHAHAHAHAHAHAH
15:52:20 <samccann> omgosh I wanna do that now!
15:52:54 <mrproper> acozine: You're from Minnesota, right?
15:53:09 <acozine> I think it'll need to be "heyacozine" - at least, the analytics only show one-word searches
15:53:29 <acozine> mrproper: I'm not "from" MN exactly, but I've lived in MN for a long time
15:54:02 <mrproper> I'm from Chicago. So I always joke that Prairie Home Companion is every midwesterner's favorite thing ever (spoiler: it isn't). So I can embed PHC quotes.
15:54:17 <mrproper> IIRC MST3k originated in MN as well, so I can make MST3k references.
15:54:32 <acozine> the town the time forgot and centuries could not improve?
15:54:45 <mrproper> Correct. All the children are above average though.
15:54:59 <acozine> heh
15:55:13 * mrproper grew up a Northstars fan.
15:56:09 <acozine> mrproper: hockey?
15:56:13 <mrproper> Yeah
15:56:17 <acozine> phew
15:56:31 * samccann Bruins 4 evah
15:56:34 <acozine> it isn't often I get sports things right
15:56:42 <mrproper> samccann: Boston?
15:56:46 <samccann> yep
15:57:26 <acozine> I grew up in the NYC area, and you don't disclose your preference for Islanders or Rangers in public
15:57:39 <mrproper> Does anyone actually like the Islanders or Rangers?
15:57:45 <samccann> oooo SNAP
15:57:51 <acozine> mostly they like the beer and the brawls
15:58:27 <mrproper> samccann: I'm really struggling with the Bruins bringing home a 3rd championship to Boston in a year.
15:59:21 <samccann> oddly, I'm okay with that :-)
15:59:41 <samccann> not that I see any games.. Lucky to get one on broadcast TV
15:59:51 <acozine> all da trophies?
16:00:07 <samccann> yeah we're getting spoiled.  I'm sure a major trophy drought is on the way
16:00:26 <acozine> do they do broadcast blackouts when tickets aren't selling for games in Boston/Chicago?
16:00:51 <mrproper> acozine: Well, on public TV or cable?
16:01:00 <mrproper> We do have blackouts but there's some nuance to it.
16:01:12 <acozine> ah
16:02:07 <mrproper> That approach almost killed the Blackhawks in the 90s. And now so much is on cable that broadcast TV is irrelevant. Streaming services is really hard with blackouts. I've had problems with that with the Cubs.
16:02:52 <acozine> the cubs have been having trouble with selling out Wrigley Field?
16:02:54 <acozine> wow
16:02:57 <mrproper> Not at all.
16:03:00 <mrproper> But MLB has blackouts built in.
16:03:05 <acozine> oh
16:03:26 <acozine> the ones here generally happen when the Twins don't sell enough tickets
16:03:35 <mrproper> https://upload.wikimedia.org/wikipedia/commons/5/59/MLB_Blackout_Areas.png
16:03:49 <acozine> and this spring, despite playing well, they haven't been selling many tickets
16:04:18 <acozine> oops, but we got distracted, and now the meeting has run over
16:04:38 <mrproper> I thought the meeting was closed. oops indeed.
16:04:39 <acozine> here, let me post the most popular searches from last week
16:04:51 <acozine> and then I can close the meeting and we can go back to the MLB
16:05:13 <samccann> priorities :-)
16:05:20 <acozine> last week we had 665 searches on Swiftype, with "route" and "file" and "command" as the most popular
16:05:42 <acozine> I don't know about "route", but the other two are clearly looking for module docs
16:06:06 <acozine> oh, there's also a link for help improving user search experience
16:06:13 <acozine> I will dig into this a bit and we can revisit next week
16:06:21 <acozine> thanks everyone!
16:06:30 <acozine> #endmeeting