14:30:55 <acozine> #startmeeting Docs Working Group aka DaWGs
14:30:55 <zodbot> Meeting started Tue Sep 10 14:30:55 2019 UTC.
14:30:55 <zodbot> This meeting is logged and archived in a public location.
14:30:55 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:30:55 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:30:55 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:19 <acozine> #chair felixfontein gundalow tributarian bcoca
14:31:19 <zodbot> Current chairs: acozine bcoca felixfontein gundalow tributarian
14:31:23 <acozine> who else is around?
14:31:31 <samccann> o/
14:31:38 <acozine> #chair samccann
14:31:38 <zodbot> Current chairs: acozine bcoca felixfontein gundalow samccann tributarian
14:31:44 <acozine> welcome, everyone!
14:32:08 <acozine> I merged two typo-fix PRs from andersson007_ this morning - thanks andersson007_ !
14:32:25 <acozine> We've got several agenda items today
14:33:11 <acozine> #topic when to publish 2.9 docs
14:33:17 <gundalow> woot
14:33:44 <acozine> we got an issue filed about adding 2.9 to the version-switcher - see https://github.com/ansible/ansible/issues/61888
14:33:59 <acozine> ah, from mrproper - thanks mrproper
14:34:43 <acozine> since 2.9 is still in beta, we don't want to link it into the version-switcher yet, but it begs the question of timing more broadly
14:35:06 <acozine> do folks have strong feelings about when docs for beta versions should be available?
14:35:40 <bcoca> i would make them available as soon as beta is cut, but i would also require a 'beta' header
14:35:48 <tributarian> I would vote for as early as possible since devel docs are already in the dropdown.
14:35:51 <bcoca> or 'unreleased'
14:36:01 <andersson007_> acozine thanks for mentioning! I have great Napoleonic plans to go thru all modules by my search-typos tool :)
14:36:25 <gundalow> +1 to what bcoca said
14:36:28 <acozine> ooh, excellent andersson007_
14:36:57 <bcoca> andersson007_: while you are in there, tkae rcae of mime?
14:37:12 <acozine> right now, we have the 2.9 docs available at https://docs.ansible.com/ansible/2.9/index.html
14:37:21 <acozine> bcoca: heh, mine two
14:38:52 <samccann> I could hard-code a 'pre released use at own risk' kind of banner into stable-2.9 itself, and then remove it at release time
14:39:08 <acozine> so . . . update the 2.9 docs banner to read something like:
14:39:50 <acozine> `You are reading documentation for an unreleased version of Ansible - use at your own risk. Use the version selection to the left if you want the latest stable released version.`
14:40:02 <acozine> then add `beta` as an option in the version-switcher?
14:40:17 <samccann> I'd just add 2.9 not 'beta'
14:40:29 <bcoca> samccann: dont think its worth it for current, lets take our time and do it generally for future releases
14:40:34 <tributarian> samccann I agree
14:40:46 <samccann> but we could probably do it either way.  If we added `beta` then I could probably get these banners working w/o the hardcoding
14:41:21 <tributarian> I think the use at your own risk could be replaced with use the documentation for the version you are running
14:41:24 <samccann> bcoca: so you are saying get this in the dropdown and the prerelease warning for the next release cycle (2.10) not this one?
14:41:32 <bcoca> yep
14:41:39 <bcoca> its not good to to things 'in middle of'
14:42:01 <acozine> if we're skipping the prerelease warning, then we definitely want the dropdown to say `beta`
14:42:19 <samccann> if we are agreed on that, we can re-title mrproper's issue to get this in the next release?
14:42:30 <tributarian> can it be 2.9-beta?
14:42:54 <samccann> the issue I have with beta - it doesn't cover rc1, any potential rc2, etc
14:43:07 <acozine> hmmmm
14:43:15 <acozine> maybe `2.9-pre-release`?
14:43:18 <samccann> and I'd prefer not to fiddle with it for every rc
14:43:32 <acozine> samccann: oh, agreed!
14:43:33 <samccann> yeah something generic would be good.
14:43:57 <acozine> if we used just `pre-release` would that simplify things for 2.10?
14:44:20 <acozine> or is it just as easy to have `2.9 pre-release` and later `2.10 pre-release`?
14:44:32 <samccann> simplify the coding, yes.  But we already have someone saying they don't know the difference between `latest` and `devel`
14:44:42 <andersson007_> bcoca: thanks, i’m afraid my tool would crash if found it
14:45:16 <tributarian> samccann: I think latest is more confusing than pre-release.
14:45:23 <samccann> so coding wise (and I'm saying just my own personal coding skills here) generic `prerelease` I and code with. `2.9-prerelease` I may not be able to. But I can still get a banner in there
14:46:05 <samccann> tributarian: agreed
14:46:29 <acozine> I'd almost vote for `current` over `latest`, but unfortunately we've worked really hard to drive traffic to `latest`
14:46:38 <acozine> and we've succeeded, which means changing now would be hard
14:47:01 <samccann> well acozine there is what google finds vs what people see.  Maybe `current` in the dropdown would make more sense than `latest`
14:47:30 <samccann> but we don't touch the urls etc
14:47:49 <acozine> I don't know - would that be less confusing, or more confusing?
14:48:20 <acozine> well, let's address the immediate problem first . . .
14:49:04 <tributarian> I think if you are going to make changes to latest, it would be better to remove it in favor of the version number. For the current issue, I am a fan of prerelease if that is easier to code.
14:49:48 <acozine> votes on adding `prerelease` to the version-switcher dropdown, pointing it at the `2.9` docs, and adding a warning banner saying it's not released yet . . .
14:50:08 <acozine> +1
14:50:11 <tributarian> +1
14:50:15 <samccann> that btw was what bcoca was saying we do for 2.10 not 2.9
14:50:39 <acozine> ah, okay, let me rephrase
14:50:40 <bcoca> that way it becomes part of the release process instead of an adhoc thing
14:51:30 <acozine> votes for amending the release process to add `prerelease` to the version-switcher dropdown when a new stable branch is cut, point it at the new pre-release version's docs, and add a warning banner to those docs
14:51:33 <acozine> +1
14:52:59 <samccann> +1
14:53:15 <gundalow> +1
14:53:28 <acozine> #chair ^^^
14:53:28 <zodbot> Current chairs: ^^^ acozine bcoca felixfontein gundalow samccann tributarian
14:53:43 <acozine> heh, well, that didn't do what I intended
14:53:47 <bcoca> +1
14:53:56 <gundalow> #unchair ^^^
14:53:56 <zodbot> Current chairs: acozine bcoca felixfontein gundalow samccann tributarian
14:54:03 <acozine> thanks gundalow
14:54:08 <bcoca> #bench bcoca
14:54:50 <acozine> I think I'd rather be a rolltop desk or something
14:55:17 <acozine> 4/0 with at least 2 abstaining . . .
14:55:19 <samccann> comfy cushion
14:56:15 <felixfontein> sorry, I'm too busy with other things; but I'm also +1 for prerelease + warning banner
14:56:34 <acozine> #agreed make the documentation for pre-release versions more visible in future by adding `prerelease` to the version-switcher and pointing it at the new pre-release version's docs with a warning banner
14:59:08 <acozine> #topic adding quotes around docs for string options that accept boolean strings: https://github.com/ansible/ansible/pull/62013
14:59:57 <acozine> I created the PR above based on a fix from sivel
15:00:07 <acozine> I'm concerned about unintended consequences
15:01:16 <acozine> the conversation started with https://github.com/ansible/ansible/issues/56788#issuecomment-496003644
15:03:58 <samccann> unfortunately I can understand sorta what the PR fix is doing, but I can't guess what else it might effect
15:04:38 <acozine> hm, I think we should publish it to the test site
15:04:54 <acozine> and ask for feedback
15:05:28 <acozine> I'm just worried that we'll end up with triple quotes around some example somewhere
15:06:16 <samccann> +1 for putting it up on test
15:08:14 <acozine> samccann: can you start the publication running? I'm not on the VPN . . .
15:08:41 <samccann> k
15:09:16 <acozine> #topic docs search update
15:10:08 <acozine> this week samccann and I looked at the Swiftype search engine
15:10:28 <acozine> we learned that it was indexing based on a sitemap, which was years out of date
15:10:46 <acozine> with the result that it kept returning results from the 2.3 docs
15:11:25 <acozine> samccann updated the sitemap and I restarted the indexing engine, and we no longer see 2.3 pages indexed there
15:11:32 <samccann> \o/
15:11:55 <acozine> this will also help with Google searches, we hope, and may be the last mile on redirecting traffic to `latest`
15:12:11 <samccann> and the site search on the lower right hand side only returns `latest` results now...
15:12:29 <acozine> \o/
15:12:38 <acozine> so . . . the next steps is consolidating the search capability on the site
15:12:44 <acozine> s/steps/step
15:13:04 <acozine> because we still have a search box in the upper left and the Swiftype search in the lower right
15:13:47 <acozine> we're thinking of moving the Swiftype search into that upper-left position and eliminating the other search box
15:14:03 <samccann> there's something in the Swifttype UI that suggests we can put the site search in another location.  so 🤞 we can replace the upper-left search w/ it
15:14:16 <acozine> does anyone know why the second search box was added?
15:14:27 <acozine> I think it happened with the release of 2.5, which was right when I joined Ansible
15:14:57 <samccann> i think it was part of the switch to the sphinx theme (as in it came with the theme) but that's a guess
15:15:08 <acozine> yeah, it definitely happened at the same time
15:15:18 <acozine> and it may have been a "side effect"
15:15:38 <acozine> but if it was intended, it would be great to know why
15:15:47 <samccann> that said, it gets a LOT of hits. So I think people are definitely using that location
15:16:03 <acozine> it's where most people look for search
15:16:10 <samccann> yep
15:16:20 <acozine> so the location is a big part of it
15:16:25 <acozine> but are there other reasons?
15:16:42 <acozine> if it's just location, then it's fine to replace it
15:17:53 <samccann> the only reason I used the upper left (besides convenience) is the lower right used to return 2.3 and that was annoying :-)  Otherwise I think the  lower left has the benefit of returning a snippet of the content (just a sentence or so) so it's easier to figure out which search result is what I'm looking for.
15:19:39 <acozine> oh, that's good to know
15:19:52 <samccann> yeah but as I test it, the snippets aren't the greatest :-(
15:19:58 <acozine> hmmm
15:20:08 <acozine> in theory we can control that, I think
15:20:32 <samccann> we should experiment for sure.
15:21:26 <acozine> okay, it doesn't seem like the search box is a hot-button issue
15:21:55 <acozine> we'll ping the channel with the PR / test when it's ready
15:22:03 <acozine> also possibly appeal for help ;-)
15:22:14 <acozine> #topic open floor
15:22:29 <acozine> does anyone have PRs to review, issues to address, questions to ask?
15:24:19 <acozine> going once
15:25:22 <acozine> going twice . . .
15:25:42 <gundalow> Nothing from me
15:26:37 <acozine> all right, thanks tributarian felixfontein samccann gundalow bcoca
15:27:01 <acozine> #endmeeting