15:00:53 <acozine> #startmeeting Documentation Working Group aka DaWGs
15:00:53 <zodbot> Meeting started Tue Jun  4 15:00:53 2019 UTC.
15:00:53 <zodbot> This meeting is logged and archived in a public location.
15:00:53 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:53 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:53 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:05 <acozine> who's around?
15:01:17 <acozine> #topic breadcrumbs
15:01:41 <acozine> #chair samccann
15:01:41 <zodbot> Current chairs: acozine samccann
15:01:59 * samccann waves
15:02:20 <samccann> can see updated breadcrumbs in action - http://docs.testing.ansible.com/ansible/2.9/dev_guide/style_guide/index.html
15:02:43 <acozine> alongchamps: andersson007_ felixfontein mrproper Pilou shaps Xaroth zoredache are you joining in?
15:02:57 * alongchamps waves
15:03:10 <acozine> alongchamps: welcome!
15:03:14 <acozine> #chair alongchamps
15:03:14 <zodbot> Current chairs: acozine alongchamps samccann
15:03:50 <acozine> the breadcrumbs show the TOCtree, not the file tree
15:04:37 <samccann> so you can click on portions of the breadcrumbs and get back to a higher level
15:04:37 <acozine> so for example, the page samccann linked to is `docs/docsite/rst/dev_guide/style_guide/index.html` but on the site it isn't linked into the Dev Guide TOC
15:04:52 <acozine> it is linked into the Community Guide TOC
15:05:13 <acozine> so the breadcrumbs show `Docs » Ansible Community Guide » Ansible style guide`
15:05:46 <felixfontein> sorry, I'm not around today
15:06:02 <acozine> felixfontein: ack, we'll miss you
15:06:32 <acozine> having breadcrumbs that mimic the toctree may trip us up in future, but it does help us move content without moving pages (thus avoiding more redirects)
15:08:40 <acozine> samccann: the breadcrumbs look great, and they bring us more up-to-date on our sphinx style as well
15:08:42 <acozine> nice work
15:08:45 <samccann> it's also very helpful to readers to be able to click back using the breadcrumbs
15:10:38 <alongchamps> I like it
15:10:45 <acozine> yes, it's good web UX
15:11:02 <alongchamps> and if something isn't in the doc tree (e.g. individual module pages) it's just Docs >> module_name
15:11:49 <acozine> yes - for example http://docs.testing.ansible.com/ansible/2.9/modules/file_module.html
15:12:33 <acozine> the module index pages aren't real toctrees
15:12:50 <acozine> oh, interesting
15:13:18 <acozine> the module index pages themselves have an interesting breadcrumb set: http://docs.testing.ansible.com/ansible/2.9/modules/list_of_cloud_modules.html
15:13:48 <acozine> I think that's useful as well - it would be great to have that nesting for the individual module pages
15:14:20 <acozine> if, for example, http://docs.testing.ansible.com/ansible/2.9/modules/ec2_vol_module.html#ec2-vol-module showed breadcrumbs like
15:15:07 <acozine> `Docs » User Guide » Working With Modules » Module Index » Cloud modules >> Amazon >> ec2_volume`
15:15:17 <acozine> but that can be a future improvement
15:15:33 <acozine> abadger1999: welcome, are you here for the DaWGs meeting?
15:15:34 <samccann> my uneducated guess is itdoesn't do it today because those module index pages are autogenerated
15:15:34 <alongchamps> that would be useful
15:15:48 <abadger1999> @acozine Yes, but just lurking ;-)
15:15:54 <samccann> (aka not TOCTree past the index page itself)
15:15:59 <acozine> abadger1999: okay, I won't make you a chair ;)
15:16:44 * samccann makes abadger1999 a comfy cushion instead
15:16:51 <abadger1999> :-)
15:16:51 <acozine> I have no idea how much work it would be to associate each module with its place in the filetree
15:16:54 <acozine> heh
15:17:18 * acozine swears we had an issue for adding breadcrumbs, but can't find it
15:17:29 <samccann> yeah i tried to find it too and can't
15:17:51 <acozine> hm, so we're having mass hypnosis or something ;)
15:18:09 <acozine> anyway, I think the breadcrumbs work is ready to merge
15:18:20 <acozine> it feels like a triumph!
15:18:52 <acozine> any other comments/questions/whatnot on the breadcrumbs work?
15:18:58 <alongchamps> none here
15:19:14 <acozine> #topic custom 404 page
15:19:33 <acozine> this is the last blocker for samccann's version-switcher
15:20:25 <acozine> I've got a branch that uses the `sphinx-notfound-page` module, but I've run into trouble making it work with our URLs - see https://github.com/rtfd/sphinx-notfound-page/issues/25
15:20:40 <acozine> I'd appreciate any testing others could do
15:21:13 <acozine> the project's author has been very responsive
15:21:39 <acozine> apparently the latest code fixes the issue on his machine, but not on mine
15:21:50 <acozine> or else I don't actually have the latest installed
15:23:54 <acozine> Steps to test:
15:24:48 <acozine> https://www.irccloud.com/pastebin/nPR1VfVm/
15:25:11 <acozine> I still see TOCTREE links with `en/latest` in them
15:25:26 <acozine> they should have `ansible/2.9` in them instead
15:27:49 <acozine> aha! I found the issue about adding breadcrumbs - it was a proposal: https://github.com/ansible/proposals/issues/147
15:29:08 <acozine> so . . . if folks test the custom 404 stuff, please post the results along with your version of Python and Sphinx here in ansible-docs any time
15:29:28 <acozine> cyberpear: welcome, are you here for the Docs Working Group meeting?
15:29:54 <cyberpear> just listening in
15:30:16 <acozine> cyberpear: sounds good
15:30:28 <acozine> #topic open floor
15:31:30 <samccann> I wasn't sure about this pr and the change it makes under choices - https://github.com/ansible/ansible/pull/57333
15:31:38 <acozine> ah, if you were kicking yourself for not submitting a proposal for a talk/panel/whatever at AnsibleFest . . .
15:31:47 <acozine> the deadline was extended to today!
15:33:10 <acozine> samccann: which choices change? lines 44-46, or lines 64-65?
15:33:57 <acozine> link for RFP for AnsibleFest: https://ansiblefest2019.eventpoint.com/cfp
15:34:13 <samccann> both - the idea of changing from ['foo']  to -foo on a separate line.
15:34:40 <samccann> and if we even had a preference or they both render fine/the same?
15:35:22 <acozine> good question
15:36:53 <acozine> here's how it looks now: https://docs.ansible.com/ansible/devel/modules/azure_rm_mariadbserver_module.html#azure-rm-mariadbserver-module
15:37:25 <acozine> so it looks like it builds a bulleted list
15:37:42 <acozine> I think that's the same regardless of the syntax in the source file
15:38:32 * acozine looks for a recent change to a choices list
15:39:06 <samccann> i think it is as well. if you look at the PR and then at that page, there are more choices there than were changed in the pr (aka both render the same)
15:39:22 <acozine> yep, looking at https://github.com/ansible/ansible/pull/57206/files#diff-b1172ea95141d0e5c2ca1b4d9714a0f0R58
15:40:01 <samccann> ok cool. I'll merge it then. thanks!
15:40:17 <acozine> and https://docs.ansible.com/ansible/devel/modules/azure_rm_manageddisk_module.html
15:40:20 <acozine> excellent
15:41:51 <acozine> several folks on this channel have been great about reviewing open PRs - thanks to cyberpear felixfontein mrproper (sorry to anyone I've omitted)
15:42:04 <acozine> we really appreciate the help
15:42:26 <acozine> the volume of docs PRs is large, and we keep trying to decrease the backlog
15:42:56 <acozine> reviews are very useful!
15:44:55 <samccann> I think I asked this before, but does ansible have any kind of policy of what to do about old/stagnant PRs?  like if there is no response for a month or two, do we close it with a polite 'please reopen when you are actively working on this pr' or something?
15:45:13 <acozine> we've got fifteen minutes left
15:45:19 <samccann> or I think there is a `need_info` label we can add to the old/stale ones?
15:45:52 <acozine> samccann: we can add `needs_info` or `waiting_on_contributor` labels
15:46:15 <acozine> for community PRs, at least ;-)
15:46:19 <samccann> one of them auto-closes a PR after a certain length of time w/ no response from the contributor, right?
15:46:29 <acozine> I'm not sure about that
15:46:31 <samccann> or did I just imagine that
15:46:38 <acozine> wishful thinking?
15:46:50 <samccann> i thought `needs_info` did... but yeah, could just be a pipedream
15:46:55 <acozine> we have some old PRs that would be great additions that are waiting on maintainers
15:47:20 <samccann> what does it mean to be a maintainer?
15:47:40 <samccann> as in could we bring some of those PRs here and have an Adopt-a-PR fest next week?
15:47:47 <acozine> someone who is willing to fix bugs and update the code in future
15:47:59 <samccann> ah code.
15:48:14 <acozine> https://docs.ansible.com/ansible/devel/community/maintainers.html#maintainers
15:48:29 <acozine> I think we do pretty well with the purely-docs PRs
15:48:36 <samccann> ah ok
15:48:41 <acozine> the backlog has quite a few docs-and-code PRs
15:48:49 <acozine> those are harder to shepherd through
15:49:30 <samccann> I would love a way to label the older PRs that we can't do anything with so we don't keep going back to them every 3 months or so, re-read, and re-learn that there's nothing we can do with them.
15:49:59 * samccann livin the pr dream
15:50:46 <acozine> if we never look at them they will never get merged or closed, though
15:52:09 <acozine> anything else on folks' minds?
15:52:20 <acozine> recent PRs to move through the system?
15:52:25 <acozine> issues that could use attention?
15:52:33 <acozine> ideas for improvements?
15:52:57 <acozine> chatter about the state of open-source projects and/or documentation?
15:52:59 <samccann> maybe we can start having an Adopt-an-Issue event
15:53:14 <acozine> sounds like a good idea
15:53:18 <acozine> shall we try that next week?
15:53:36 <samccann> if we can find a few each week and add to the agenda?
15:53:43 <acozine> +1
15:54:08 <acozine> maybe we could pick a theme for next week and see how many issues relate to it
15:55:29 <samccann> +1
15:55:55 * acozine fails again with the IRC commands
15:56:17 <acozine> #info let's add Adopt-an-issue with a theme to next week'd DaWGs agenda
15:56:36 <acozine> we've got four minutes left
15:57:52 * acozine hearing no topics for discussion, calls the meeting to a close
15:58:02 <acozine> thanks folks!
15:58:08 <acozine> #endmeeting