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