14:31:04 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:04 <zodbot> Meeting started Tue Dec  3 14:31:04 2019 UTC.
14:31:04 <zodbot> This meeting is logged and archived in a public location.
14:31:04 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:04 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:04 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:12 <acozine> who's around?
14:31:34 <samccann> o/
14:31:45 <tremble> \o
14:31:55 <acozine> #chair samccann tremble
14:31:55 <zodbot> Current chairs: acozine samccann tremble
14:32:00 <acozine> welcome tremble!
14:32:12 <acozine> hm, that sounds a bit weird, doesn't it?
14:32:17 <tremble> :)
14:32:18 <acozine> tremble: welcome!
14:32:35 <acozine> at least I didn't put a comma in there
14:32:51 <acozine> "welcome, tremble" is a mixed message if ever I've heard one
14:33:45 <acozine> alongchamps: andersson007_ cyberpear epereira felixfontein  you folks talking docs today?
14:33:45 <samccann> heh
14:34:26 <acozine> gundalow: madonius Pilou shaps zoredache . . . talking docs?
14:34:37 <alongchamps> not today, I get to shovel out my car :)
14:34:45 <tremble> if felixfontein isn't around it's probably worth mentioning one of his latest PRs : https://github.com/ansible/ansible/pull/65437
14:34:53 <acozine> alongchamps: what fun for you!
14:35:06 <alongchamps> oh yeah. day 2 of 2
14:35:09 <acozine> spring is coming . . . someday
14:35:47 <samccann> same here on day 2 of the snow shovelling
14:36:41 <acozine> we got lucky here in MN (well, central MN - Duluth and northern MN got socked with 22 inches) - storm  dropped more rain than snow
14:38:21 <acozine> all right, let's chat about search!
14:38:27 <acozine> #topic docsite search
14:38:35 <acozine> you wanna drive, samccann ?
14:38:51 <samccann> sure
14:39:04 <acozine> cool
14:39:25 <samccann> so today, we have two search options - opensearch on the top left with a little search box, and swifttype search in the lower left.
14:40:12 <samccann> swiftype is a stronger more flexible search engine so we want to move to using that one.  The other one we can either just make disappear, or we can try to move swiftype up to use that existing search box
14:41:00 <acozine> my sense is that the opensearch is more frequently used, but the swiftype returns better results - and my guess is that's because most people expect search to be at the top of the page, either in the top banner or in the left nav
14:41:03 <samccann> I don't have the stats handing, but I seem to recall we have WAAAAAY more people using the upper left search box than the lower right (sorry it's right) swifttype. So that's in favor of keeping the box, but changing the search engine underneath
14:41:35 <acozine> +1 to using swiftype
14:41:45 <acozine> +1 to moving it up to the upper left
14:42:10 <samccann> +1 for both from me as well
14:43:05 <samccann> the other gotcha to solve - swiftype today only returns 'latest' results, no matter what version of docs you are looking at
14:43:21 <samccann> It's a solvable problem (tower docs figured it out).
14:43:58 <tremble> I didn't even *notice* the bottom right search...
14:44:00 <samccann> The other gotcha is we don't currently know how to test changes on swiftype without affecting the live docs so to speak
14:44:08 <acozine> tremble: yep, exactly
14:44:17 <samccann> yeah tremble I almost never use it myself because it's not obvious
14:44:51 <samccann> that said, we get around 1000 searches a week using that lower left box, which makes me reluctant to experiment 'live' so to speak.
14:45:19 <acozine> I find myself using the upper left search, getting frustrated because none of the results show me the page I'm looking for (often a page I know is there, because I've edited it), then using the Swiftype search
14:45:43 <samccann> yep, it is a better search for sure.
14:46:16 <samccann> We also need a way to let people know when the switch happens. Not sure what communication channels we can use/abuse for that
14:47:19 <acozine> all the chat channels, all the mailing lists, I guess
14:47:46 <samccann> is reddit worth hitting as well, or overkill?
14:48:04 <acozine> though I suspect that most people don't realize we have two search boxes now, and won't notice when we replace the engine under the upper left box
14:48:20 <acozine> sure, we can get out on reddit too
14:48:29 <acozine> transparency is key
14:48:51 <acozine> we can ask the marketing and community teams to tweet the change too
14:49:40 <samccann> yeah it's just those 1000 peeps a week (or 1000 searches). Small in ansible sense, but still big in my eyes o-o
14:50:08 <samccann> #agreed - replace opensearch with switftype and remove the duplicate search box in the lower right
14:50:14 <acozine> communicating the change doesn't worry me as much as executing and testing it - folks who found the lower right search are presumably paying attention
14:50:31 <acozine> (not that others aren't . . . )
14:51:14 <acozine> so what are the blockers to testing the change?
14:51:30 <samccann> I need to get facetted search working for sure
14:51:41 <samccann> which likely needs help from swifttype.
14:52:03 <acozine> that's to get the engine to search within the version the person is on?
14:52:52 <samccann> yes. I have to add metadata to all the maintained versions of ansible (pretty easy). But then Tower did something 'different' that what we have in our html so need to get help with that
14:53:17 <samccann> From there, we still have two search boxes on the test site, though it 'seems' swifttype will use both.
14:54:06 <samccann> So if we got everything working w/o changing the search engine itself, we could publish and have the upper left box and lower right box BOTH working for a short time on swifttype. Then we could change the engine once we are sure its working
14:55:05 <acozine> Can we try it first on the test site?
14:55:05 <samccann> And of course we could do this on devel only to start, but again, it's the same search engine on everything (for swiftype) so I 'think' it will change everything else as well. But latest and others would still have opensearch until we are sure things work.
14:55:24 <samccann> that's the gotcha I don't know about. right now, one engine rules them all so to speak
14:55:36 <acozine> ah, I see
14:55:56 <acozine> so maybe the first step is doing whatever optimization we need to do on the search engine itself
14:55:59 <samccann> without adding another engine (and the associated costs) I don't know how. but it must be solvable. I can't imagine they don't have an option to test out changes first
14:56:38 <samccann> first step is facets in our metadata and republish those pieces. then  yeah, get help getting facets working
14:56:45 <acozine> while we do that, we can leave the opensearch box in place, so all those users who don't know about the swiftype search won't see any changes
14:56:46 <samccann> That all will just affect the lower-right box
14:56:55 <samccann> eggzacly
14:56:59 <acozine> yeah, that sounds like a great plan
14:57:28 <acozine> then when it works the way we want, we can make the upper left location use Swiftype
14:57:38 <acozine> then when that works, we can remove the lower right
14:57:45 <samccann> #agreed start with facet metadata and get that working on existing swiftype site search (lower right box) with help from swiftype
14:58:30 <samccann> #agreed Then get the uper-left to also use swiftype (removing opensearch) on devel only.
14:58:45 <samccann> #agreed finally, make the switch on all maintained releases and remove opensearch entirely
14:58:51 <samccann> sound about right?
14:58:58 <acozine> yep
14:59:38 <samccann> any thoughts/reasons to leave older doc versions with the opensearch option? (like 2.7, 2.8)? I think we could. Dunno if we should or shouldn't?
14:59:56 <samccann> it is a code and feature change if that makes sense? We don't usually have those in docs land
15:00:03 <samccann> (well docsite feature I should say)
15:00:17 <acozine> my vote would be to backport the search changes to all supported versions
15:00:40 <samccann> I'm fine with that as well, I just don't want us breaking our own rules to to speak.
15:00:49 <acozine> otherwise we don't get the benefit of searching "within the version" for three more releases
15:00:53 <samccann> though it's not in the rpm etc so maybe it doesn't matter
15:01:03 <samccann> oh true.
15:01:22 <acozine> yeah, I think we can get an exemption from the "we don't backport features" rule, since this feature won't affect any playbooks or roles or anything
15:01:24 <samccann> ok well that's how I worded the agrees so I think we're good here
15:01:39 <acozine> \0/
15:02:29 <acozine> Shall we look at Felix's PR?
15:03:02 <acozine> #topic PR #65437
15:04:24 <acozine> ah, it's the dreaded "missing D" problem - module docs have `require` instead of `required`, or just have missing documentation
15:05:12 <acozine> oh, dear, 902 violations
15:05:17 <samccann> heh
15:05:41 <samccann> I like the PR.  I worry (not related to this but in general) that we have massive ignore files
15:05:56 <acozine> ah, and tremble fixed 30-odd of them
15:06:08 <samccann> woo hoo!!! go tremble !!!
15:06:28 <acozine> yeah, the faster we fix those, the better
15:06:48 <samccann> semi related question - how do collections use these ignore files (or not use them) when things are moved?  Will movers suddenly see ton of errors to fix?
15:07:05 <acozine> I don't know that we have an answer for that
15:07:14 <samccann> oh nevermind.. ugh... galaxy/automation hub has its own code. What we fix here doesn't get fixed there I don't think
15:07:21 <acozine> but it's one of the reasons we should fix these things now if we can
15:07:25 <samccann> not unless we 'manually' tell them so to speak
15:07:43 <acozine> well, theoretically collection owners will run their own tests
15:07:52 <acozine> I'm just not sure how that works in practice
15:08:13 <samccann> yes but this specific fix checks that docs match argspec. Is there anything in collection land testing for that?
15:08:21 <acozine> maybe we could run the docs tests when we build the collections docs?
15:08:36 <samccann> also, imagine this scenario - someone creates a new collection. the docs have some of these recently fixed mismatches
15:08:57 <samccann> abadger1999 code pulls those docs over to ansible... will it run through these tests again and fail?
15:09:42 <acozine> yeah, I don't know what happens
15:09:42 <samccann> or do the sanity tests get bypassed when it all comes from a collection? my guess is yes (any sanity tests would be in the collection itself or perhaps if certified, within mandated certification tests)
15:09:47 <acozine> I mean, if they're fixed, it's not a problem
15:09:59 <acozine> but if they're discovered but not yet fixed . . .
15:10:18 <acozine> well, the PR in front of us now is worthwhile no matter what happens in future
15:10:24 <samccann> this is just one category of recent fixes that may not have been picked up in any other project. So it's also a communications issue
15:10:56 <acozine> theoretically, the modules should leave core when they get added to the collection
15:10:59 <samccann> oh yeah, I'm just debating what 'else' has to happen and how do we keep that communication loop open. Maybe we need a new github tag. 'galaxy-take-notice' :-)
15:11:05 <acozine> heh
15:11:16 <acozine> yeah, good question, good idea
15:11:50 <acozine> any other thoughts about PR 65462?
15:11:53 <samccann> i'm actually serious on this. We can ping gundalow to help us figure out how to do that and if there's an automagic way it can detect when someone is playing with docs vs argspec stuff and flag it
15:12:16 <samccann> do we want to test it locally before merging? otherwise I'm fine with it
15:13:49 <acozine> it won't affect the docs build itself, it just adds a test to the CI suite
15:14:00 <acozine> and since it's passing CI, presumably the test works
15:14:17 <samccann> ok
15:14:22 <acozine> and since the failures are in the ignore.txt, presumably they needed to be there
15:14:31 <acozine> unless Felix is just messing with us . . .
15:14:39 <samccann> hahah
15:14:49 <samccann> too soon for April Fools pranks :-)
15:15:18 <acozine> heh
15:15:20 <acozine> merged
15:16:44 <acozine> tremble: thanks for the copyediting changes on top of the sanity test fixes in 65462
15:17:12 <acozine> in the "no good deed goes unpunished" category, the copyedits mean it will take a little longer to review the PR
15:18:24 <acozine> #topic edits to the Filters page
15:18:59 <acozine> I'd appreciate some eyes on a draft rewrite of the Filters page
15:19:08 <acozine> currently posted to `devel` on the testing site
15:19:11 <acozine> http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_filters.html
15:19:36 <acozine> main goal of the rewrite is to make things easier to find
15:20:39 <samccann> Do we want to split up the page as well? Search engines don't find all the 2nd level headings I don't think
15:20:52 <samccann> (or perhaps in a separate pr sinc this one has a lot of good work already)
15:21:01 <acozine> if a user is coming to the page looking for "how do i get the square root of a number" or "how do I parse a date out of this"
15:21:14 <acozine> samccann: that's an interesting idea
15:21:40 <acozine> we could have a whole section devoted to filters, though some of the topics are huge and others are quite small
15:22:25 <samccann> do we know the 'important/most used' filters? Those would be good to make as search friendly as possible
15:22:42 <acozine> I don't know for sure
15:22:47 <gundalow> samccann: acozine Hi. In other meetings. Can we sync up later?
15:22:57 <acozine> gundalow: sure, sounds good
15:22:59 <samccann> sure thanks gundalow
15:24:06 <samccann> well my nickel on the existing PR is let's get it reviewed and merge
15:24:17 <acozine> it's not even a PR yet
15:24:27 <samccann> then we can debate if its worth subpages etc
15:25:00 <acozine> all right, I'll give it one last read-through today and create a PR
15:25:21 <acozine> it's already going to be a big PR
15:25:30 <samccann> I'll take a look after the meeting as well on the test site
15:25:39 <acozine> samccann: thanks!
15:26:00 <samccann> should we open the floor?
15:26:11 <acozine> yep
15:26:17 <acozine> #topic open floor
15:26:50 <acozine> tremble: anything you want to highlight other than your `require/required` fix PR?
15:26:55 <tremble> Nope
15:27:11 <tremble> Mostly wanted to lurk to see what's going on
15:27:25 <acozine> excellent!
15:27:51 <acozine> lurking is the first step
15:28:05 <acozine> before you know it you'll have a five-hour-a-week docs habit
15:28:16 <acozine> it's addictive
15:28:20 <acozine> especially copyediting
15:28:49 <samccann> heh
15:28:53 <acozine> but lately the WG meetings have been very quiet
15:29:05 <samccann> does that make us docs pushers... or a gateway drug??
15:29:07 <acozine> the PRs keep coming in, though
15:29:23 <acozine> samccann: maybe both?
15:29:41 <acozine> and now my mental soundtrack is singing Tom Lehrer's "The Old Dope Peddler"
15:29:47 <tremble> Well for now I'm just trying to get the AWS modules into better shape, they're the ones I use :)
15:29:56 <acozine> the only ones?
15:29:58 <acozine> wow
15:30:01 <acozine> okay, good to know
15:30:38 <tremble> Well I use other modules too, but they're the ones I use most heavily
15:30:44 <acozine> usually folks use cloud modules as a prep step
15:30:46 <acozine> ah, gotcha
15:31:02 <acozine> well, thanks for bringing them "up to code" as they say in the building industry
15:31:46 <acozine> all right, that's our Hour of Docs for today
15:31:57 <acozine> thanks tremble samccann gundalow and all you lurkers out there
15:32:03 <acozine> join us here any time!
15:32:14 <acozine> questions and ideas always welcome
15:32:24 <acozine> #endmeeting