14:32:26 <samccann> #startmeeting DAWGS (Documentation Working Group)
14:32:26 <zodbot> Meeting started Tue Feb  4 14:32:26 2020 UTC.
14:32:26 <zodbot> This meeting is logged and archived in a public location.
14:32:26 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:32:26 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:32:26 <zodbot> The meeting name has been set to 'dawgs_(documentation_working_group)'
14:32:36 <samccann> so who's around to talk the docs??
14:32:42 <cbudz> *present*
14:33:37 <samccann> #chair cbudz
14:33:37 <zodbot> Current chairs: cbudz samccann
14:34:38 <samccann> anyone else around? felixfontein gundalow cyberpear mrproper ??
14:35:27 <bcoca> you can leave msg after the beep ...
14:35:31 <samccann> heh
14:35:44 * samccann tosses comfy cushion at bcoca anyway
14:36:04 <samccann> So let's get started
14:36:06 * bcoca is using standing desk, but will save cushion for later
14:36:11 <samccann> #Status Updates
14:36:18 <samccann> oh duh
14:36:22 <samccann> #topic Status Updates
14:36:27 <samccann> that's better
14:36:57 <samccann> #info swiftype search up and running for a week  on latest. So far so good. 28K search hits
14:37:46 <samccann> this will bring us better search stats and the goal is to use those to help us understand what folks are looking for, fix problem areas if we find them etc.
14:38:09 <cbudz> that's awesome
14:38:11 <samccann> I also did some improvement on the network docs for the new resource modules they are developing at a FURIOUS PACE I might say
14:38:33 <samccann> any other updates?
14:38:54 <cbudz> I've got some feedback for issue60282 that I'll create a PR for today or tomorrow
14:39:17 <cbudz> finished reviewing the Collections FAQ doc and categorized that info to split between AH and Galaxy
14:39:48 <cbudz> also did some research on re-designing the docs landing page
14:39:52 <samccann> #info Collections FAQ document in the works, some of which will be for Galaxy and other parts specific to Red Hat Automation Hub
14:40:09 <samccann> o kewl.  You got some mad skills in that area cbudz?
14:40:34 <cbudz> I've got some IA/UXX experience on this topic
14:40:45 <samccann> #info gathering ideas for the docs landing page to help clean it up
14:41:23 <samccann> that would be great! *somewhere* there is a mockup design that was done some time past. I'll try to dig that up for ya.
14:41:48 <samccann> I have remedial html skill so between us, we might be able to make some progress on that page. (docs.ansible.com main page )
14:42:32 * bcoca edits html in vim and knows <tr><td> magic!
14:42:49 <samccann> for the readers at home, last week (or possibly before?) this was the subject of a reddit thread, pointing out that it lacks any kind of cross-site search.
14:42:51 <cbudz> if you can pass that along it would be great. I'll get some wireframes together at some point and share along with supporting documentation
14:43:11 <samccann> nice!  and bcoca can write it all w/ vim!!!
14:43:15 <samccann> (muuhahahaha)
14:43:45 <samccann> there's likely enough skills floating around here to get something going for sure.
14:43:54 <samccann> Anyone else with a status update?
14:43:54 <bcoca> yould be suprised how much i used to do that for docs site before we had docs team
14:44:27 <samccann> file that one under things you should NOT admit to bcoca :-) now we know who to bug for help!!
14:45:14 <bcoca> oh, you can bug me as much as you want ... just dont expect that to actually result in anything ...
14:45:44 <samccann> hehe
14:45:53 <samccann> ok steaming full speed ahead
14:46:05 <samccann> #topic Html links on module parameters
14:46:30 <bcoca> to each option vs the 'options table'?
14:46:34 <samccann> This is a fun one that came from the community with a good deal of help from felixfontein
14:46:39 <samccann> to each option!
14:46:41 <bcoca> nice
14:46:46 * samccann checks if it's on devel now
14:47:15 <bcoca> ^ has been on my wish list forever .. but waaaay down in priority queue
14:47:32 <bcoca> same for results structure and examples
14:47:34 <samccann> https://docs.ansible.com/ansible/devel/modules/ios_interfaces_module.html#parameter-config/mtu
14:48:03 <bcoca> ^ need to put anchor a bit higher, i get 1 line AFTER mtu
14:48:38 <samccann> #info you can now link directly to a module parameter/option, return value
14:48:46 <bcoca> same with every one i test, im one line below
14:48:48 <samccann> #link https://github.com/ansible/ansible/pull/66895
14:49:28 <samccann> ah didn't catch that yesterday that it was a line below. can you take a quick look at that PR and tell if that's an easy fix or not?
14:49:50 <bcoca> also an issue with subparameters as they can be dupe, e.g config.mtu vs other.mtu in same module
14:50:18 <bcoca> right now subparams are top level name so /mtu would be ambiguis, might be worth doing config_mtu as anchor or some other separator
14:50:33 <bcoca> . might be better since it is not allowed in parameter name
14:50:48 <bcoca> /config.mtu
14:51:03 <samccann> #info some areas to improve on this work - link currently goes one line under the parameter
14:52:04 <samccann> #info subparameters can have dupicate names  - config.mtu vs other.mtu in same module. Might be better to combine parameter and subparameter in the anchor config.mtu vs just mtu
14:52:12 <bcoca> i see it works for return also, /return-before
14:52:17 <samccann> good stuff. yep
14:52:19 <bcoca> using return as prefix and - as separtor
14:52:45 <samccann> you seeing a problem there with the - separator?
14:52:51 <bcoca> ^ similar issues with above, also would worry about 'return' being a parameter, but dont see that as big problem
14:53:00 <bcoca> no, was just describing
14:53:06 <bcoca> - works as well as . can
14:53:06 <samccann> ok kewl thanks!
14:53:22 <bcoca> i would keep it consistent then
14:53:50 <samccann> # info - separator works as well as .  But avoid _  (underline) as that is allowed in the parameter name itself
14:54:13 <bcoca> +1
14:54:36 <bcoca> love teh feature, tired of linking to table and people still 'not finding' the parameter, mostly cause scroll ...
14:54:48 <samccann> heh yep.
14:55:01 <samccann> anything else on this topic before we shuffle on?
14:55:01 <bcoca> anything that requries 'less reading' seems to make docs more effective .... ah .. the irony ...
14:55:44 <samccann> very very true.  Thus our own discipline of minimalism... short and to the point.
14:56:25 <samccann> and you've been upgraded
14:56:28 <samccann> #chair bcoca
14:56:28 <zodbot> Current chairs: bcoca cbudz samccann
14:56:46 <samccann> ok shuffling on
14:56:52 <samccann> #topic changing Agenda link
14:57:29 <samccann> I'll ping gundalow on this, but once a year, we should start a new agenda comment. Seems other working groups do this and it helps a bit on the scroll scroll scroll
14:57:44 <samccann> to get to the comment of the current meeting week.
14:58:06 <samccann> #action samccann to create a new agenda comment/link for the new year
14:58:31 <samccann> I'm sure there's places I need to update that link beyond just creating the new comment and shutting down the old one.
14:59:45 <samccann> ok before we buzz buzz about PRs and issues, gonna open the floor
14:59:49 <samccann> #topic Open Floor
15:00:00 <samccann> Anyone lurking who has an item to bring up? now's your time
15:00:19 <cbudz> nothing outside of the landing page proposal
15:01:29 <samccann> one thing I'll mention... our own Fearless Leader acozine is out with the flu.
15:01:31 <bcoca> add 'helper' ansibull to landing page 'what do you want to automate today?' ...
15:02:06 <samccann> erm.. not sure what that means bcoca?
15:02:23 <bcoca> clippy joke ... nvmd ... must keep day job ...
15:02:50 <samccann> hehe okay that's what I thought... but sometimes what I think you are saying as a joke is actually something real :-)
15:02:59 <samccann> let's CHATBOT THE DOCS!!!
15:03:14 * bcoca lives in between <sarcasm> </sarcasm> tags
15:03:20 <samccann> heh
15:03:57 <samccann> ok ...moooving on
15:04:08 <samccann> #topic Docs issues - 228
15:04:35 <samccann> So we have 228 open docs issues. There's an interesting one I just see (based on title alone) that I'd like us to take a quick look at
15:04:51 <samccann> #link https://github.com/ansible/ansible/issues/67072
15:05:08 <samccann> sight-unread so to speak, it's labeled as 2.5 which we no longer support.
15:08:17 <samccann> unfortunately it's beyond my immediate comprehension whether the info the OP is looking for is in the current docs or not. I'll have to read more on that one. I thought it might be an easy close but maybe not
15:09:26 <samccann> This is another interesting one
15:09:29 <samccann> #link https://github.com/ansible/ansible/issues/67008
15:10:11 <samccann> someone wants our eol banner on even older docs.  The problem is - the older docs (prior to 2.5) have a different theme, so it's not an easy fix.
15:10:25 <samccann> (at least not a simple backport like the rest were).
15:11:02 <samccann> #info doc versions prior to 2.5 don't have the same html theme and thus can't benefit from a quick backport to the EOL banner.
15:11:02 <cbudz> at what point do unsupported doc sets become deprecated and taken down?
15:11:09 <samccann> never
15:11:19 <samccann> at the moment anyway.
15:11:41 <samccann> But that is certainly a conversation I'd like to have.
15:12:02 <samccann> that said, I think there are people still on old unsopported releases.
15:12:36 <samccann> so if we could easily find a way to mark them all as 'this stuff is ancient' that would allow us to leave them up for those still lingering
15:12:40 <samccann> on old versions
15:13:16 <samccann> I 'think' our docsite goes down to 2.3.  But there is some even older stuff up on readthedocs that we have no control over (I want to say 2.2 and maybe 2.1?)
15:13:52 <cbudz> can we limit issues rasised for docs to only those supported versions?
15:14:09 <samccann> oh yeah we would normally not fix ANYTHING prior to 2.7
15:15:04 <samccann> the only exception was this EOL banner, since we created that around the 2.8/2.9 timeframe and it seemed a wortwhile exception to backport it as far back as it would easily go (to 2.5).  so yes, we could just close and say we don't update that far back etc.  And we might have to do that
15:15:20 <cbudz> can we make that publicly facing policy to cut down on issues like that one?
15:15:45 <samccann> if it proves too difficult.  But my html skills have gotten a tiny bit better, so I might be able to handle this one. Worth a couple of hrs checking imo.
15:16:04 <cbudz> happy to help
15:16:06 <samccann> It is in the sense that it's clearly in our release and maint strategy when things go unsupported
15:16:33 <samccann> ok we can dig into it later this week maybe
15:17:00 <cbudz> kewl
15:18:22 <cbudz> I need to break off to get ready for my next meeting. I'll drop in the issues this afternoon and try to wrangle a few
15:18:37 <samccann> ok thanks cbudz! winding up here anyway
15:18:41 <samccann> moving on to
15:18:59 <samccann> #topic Docs PRs at 105
15:19:25 <samccann> And if that isn't an indication of Fearless Leader out sick... acozine is much better at doc PR wrangling than I am for sure!
15:20:04 <samccann> there's a handful or more backports that I don't have the rights to merge.
15:20:42 <samccann> #info - please continue to pop into docs PRs and add reviews/comments. It helps move them along - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
15:21:12 <samccann> That's about all I have... and I think bcoca has gone back to being a cushion, so Imma talkin to myself at this point I think :-)
15:21:15 <gundalow> samccann: hi, currently having coffee with felixfontein & resmo.
15:21:37 <samccann> oh I'm not talkin to myself then!
15:21:43 * samccann waves at the coffee crowd
15:21:57 <gundalow> You can create a new agenda issue, or what might be better is to hide precious items in the agenda.
15:22:38 <samccann> yeah we have been hiding the very older ones, it's still a lot of scrolling. I seem to recall someone saying other teams just create a new agenda issue each year to help with that
15:22:38 <bcoca> sorry, conflicting meetings
15:22:56 <samccann> no worries bcoca. sometimes we draw a crowd, sometimes we don't.
15:22:59 <bcoca> 2.5 one is really not docs issue as much as error msg bug
15:24:30 <samccann> ok gonna end this meeting unless someone has  final topic?
15:25:41 <samccann> ok it's a wrap!
15:25:45 <samccann> #endmeeting