14:31:32 #startmeeting Docs Working Group aka DaWGs 14:31:32 Meeting started Tue Feb 18 14:31:32 2020 UTC. 14:31:32 This meeting is logged and archived in a public location. 14:31:32 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:31:32 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:31:32 The meeting name has been set to 'docs_working_group_aka_dawgs' 14:31:40 * samccann waves 14:31:53 hello, good morning, good afternoon, good evening! 14:31:58 #chair samccann 14:31:58 Current chairs: acozine samccann 14:32:05 who is around? 14:33:03 I'm around, but only for ~3 minutes ;) 14:33:06 andersson007_: baptistemm cbudz cyberpear dag felixfontein kmaxwell madonius mrproper Pilou shaps tributarian you folks ready to chat docs? 14:33:19 felixfontein: that's very efficient of you! 14:34:11 I am pleased to be here, but maybe don't have a lot to say :-) 14:34:24 welcome kmaxwell 14:34:34 #chair kmaxwell 14:34:34 Current chairs: acozine kmaxwell samccann 14:34:44 *waves* I'm here, just wrapping up a troubleshooting session with another writer at the moment 14:34:53 we generally like to have as much furniture around the place as possible ;-) 14:34:58 #chair cbudz 14:34:58 Current chairs: acozine cbudz kmaxwell samccann 14:35:08 looks like a light agenda today 14:35:18 #topic how to add agenda items 14:36:05 oof, I'm having network issues 14:36:15 we started a new GitHub issue for the DaWGs agendas for 2020 14:36:45 here's a link to the issue: https://github.com/ansible/community/issues/521 14:36:58 the last comment is always the upcoming meeting's agenda 14:37:19 * gundalow waves 14:37:28 I'm actually here this week 14:37:31 #chair gundalow 14:37:31 Current chairs: acozine cbudz gundalow kmaxwell samccann 14:37:38 gundalow: awesome! 14:37:52 * gundalow sits 14:37:59 so . . . the agenda is open to all - anyone can add an item to it 14:38:28 just add a comment to the issue - you can link to PRs and issues on any GitHub repo 14:39:02 so if you want feedback or help on anything docs-related, feel free to add it to the agenda 14:39:08 agenda is linked from the wiki, which is super handy if you're struggling to find it 14:39:37 kmaxwell: ah, excellent - is the link updated for the new 2020 agenda? 14:40:02 the link uses labels so is always up to date (I think) 14:40:31 if you're searching for it manually remember it is in the ansible/community repo 14:41:24 rather that the ansible/ansible repo, which is where you might start your search if you're naive like me :-) 14:41:44 s/rather that/rather than/ 14:42:02 kmaxwell: we have enough issues in the ansible/ansible repo without opening ones we know we will never close ;-) 14:42:48 :) 14:43:00 :) 14:43:45 samccann: can you do your IRC make-it-pop-in-the-minutes magic on "feel free to add stuff to the agenda (link)" 14:44:01 someday I will learn all the right IRC commands 14:44:15 `#info foo` 14:44:27 ah, thanks gundalow 14:44:59 #info anyone can add items to the agenda for the Docs Working Group (DaWGs) - the 2020 agenda is https://github.com/ansible/community/issues/521 14:45:01 #info anyone can add to the agenda at https://github.com/ansible/community/issues/521 14:45:11 haha sorry... slow on the uptake today 14:45:15 heh, now it will really stand out! 14:45:30 see we really MEAN IT! 14:45:34 all right, first actual agenda item is status updates 14:45:35 heh 14:45:42 #topic quick status 14:46:04 Gotta say your idea of putting the broken links in issues and asking for help worked like a charm! 14:46:18 oh, excellent! 14:46:24 #info -community help on docs broken links has been fantastic! most issues are closed already! 14:46:43 thanks to everyone who stepped up! 14:47:09 we are back under 75 open PRs marked `docs` on the ansible/ansible repo 14:47:28 https://github.com/ansible/ansible/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Adocs+ 14:47:46 there are still some that could use reviews, especially on the first page 14:48:13 a lot of the older ones combine code and docs, and it's tough for the docs team to merge them 14:48:27 #info looking for help reviewing open docs PRs, especially the first page at https://github.com/ansible/ansible/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Adocs+ 14:49:13 anyone who sees a PR that could be merged as-is or merged with a few tweaks (or even merged with some more serious work) please put a review on it and ping us here! 14:49:37 gundalow: do you want to talk about the timeline for the Great Module Migration? 14:49:51 Sure, thanks 14:49:58 #topic Collections 14:50:29 #info I started https://github.com/ansible-collections/overview/pull/3 which aims to give some more context around Collections (what/why/how) 14:51:46 #info i hope for ^ to be a living document, by that I mean we will keep on updating it with new questions (and hopefully answers); examples; and links to other bits of documentation 14:52:33 do you envision that needing to be in docs.ansible.com/ansible? or wait for the dust to settle before moving some of it into the docs? 14:52:51 gundalow I have some collections FAQ info that came in last week I'll see how i can add to that 14:53:34 keep in mind gundalow's stuff is upstream (i think? does it mention certified collections??) 14:53:48 * samccann goes and reads 14:54:04 cbudz: excellent, feel free to add `suggestion` for new section in that PR, or raise a PR once I've merged it. I hope to get it merged in the next couple of days 14:54:34 Yup, this is upstream (Community) only, so no mention of Automation Hub, Ansible Automation Platform, etc 14:55:09 sammccann, good point. There's some general collections info that was included in the FAQ we're working, so if i can work into the PR. 14:55:11 samccann: stuff is way too fluid for docs.ansible.com. That said I'm working on another PR to add a few specific bits into `developeing_collections` 14:55:18 -typos 14:55:46 If there is a good home for some of the topics in docs.ansible.com I'll raise PRs and link from gh/ansible-collections/overview 14:55:48 gundalow - is it worth putting a link from 'developing collections/using collections' in docs to that readme once it's merged? 14:56:26 That's a great idea, I'll do that 14:57:56 in the last couple of weeks, we've talked about sharing the dates for the transition to Collections 14:58:07 we have more information now, so I'm going to post that here 14:58:29 remember that if the core team runs into challenges, these dates may change 14:59:23 #info preliminary start date for the Collections Transition: ansible/ansible devel branch will freeze on March 2nd for the transition 15:00:25 so if you have things you'd like to see merged into the main repo, please prioritize them NOW 15:00:27 I'm thinking about some project status board as well. Once we know what that looks like I'll update that page 15:00:53 the rest of this week and all of next week . . . that's all the time we have to get things merged 15:01:09 but no new modules will be accepted 15:01:12 Yes, mass merge of PRs, especially things that would end up in community.general (ie not have a dedicated collection) would be really good 15:01:17 samccann++ 15:01:34 * gundalow needs to drop off now, Thanks 15:01:39 Feedback on the PR welcome 15:01:42 #info we have already instituted a No New Modules policy 15:01:53 jinx! waas just typing that 15:01:53 all new modules must be developed in a collection 15:01:55 heh 15:02:04 gundalow: thanks! 15:05:11 shall we have Open Floor? I figure now and then we should make amends for only opening the floor in the last two minutes of the meeting 15:05:23 by opening the floor early 15:05:34 not that the floor is ever really closed in a DaWGs meeting ;-) 15:05:43 #topic open floor 15:06:06 any questions (about collections or docs or anything else, really)? 15:06:27 suggestions, ideas, PRs that need attention, issues that piqued your interest, etc.? 15:06:33 yeah feel the same about opening the floor earlier than we usually do 15:07:57 i do have a Great Module Migration topic to discuss 15:08:09 I have a quick Q about an issue 15:08:11 * samccann waits a bit in case someone else has something 15:08:24 cbudz: excellent, what's the question? 15:08:38 I grabbed this yesterday and started working on it: https://github.com/ansible/ansible/issues/65805 15:09:13 great! 15:09:31 Ideally i would imagine it should include some example of testing a role using Molecule within a larger secion on testing roles 15:10:06 but is there anything like that in flight? I don't think I turned up anything specific about testing roles when I searched the docs on testing 15:10:39 I believe there are dedicated docs for molecule in the project repo, but we do not currently publish them to docs.ansible.com 15:11:07 updating those has been on the "big list of docs to-do" for a long time 15:11:18 someone is working on dedicated molecule docs (as in a full docset). But I think we'd still need something in ansible test docs to point to it when it's available. 15:11:24 * samccann tries to dig out a name 15:11:39 Ok, that's good to know 15:11:43 current docs are at https://molecule.readthedocs.io/en/latest/ 15:12:23 I would love to see those docs "brought into the fold" on docs.ansible.com 15:12:30 along with the galaxy docs 15:13:15 cbudz: for some background, Molecule was a community project that RH/Ansible adopted 15:14:00 someone is working on molecule docs, who had the idea to separate our ansible sphinx theme into a... er... pip-installable package? so we could all use the same theme w/o copy/pasting between repos etc 15:14:28 oh, right, I'd forgotten that 15:14:37 that will be awesome! 15:14:53 #info cbudz working on linking docs.ansible.com test section to molecule docs if we can find the owner of said docs 15:15:27 I'll snoop around and please feel free to share info if it comes along 15:15:35 will do cbudz 15:17:20 other questions, concerns, suggestions, ideas? 15:17:43 I had one 15:17:53 #topic What to do with module links in porting guides 15:18:09 oof, yes, we need to work on that 15:18:29 This has to do with the Great Module Migration. Once they all move into a collection, the module docs will have moved to a new location as well (within docs.ansible.com once the docs pipeline is working) 15:18:53 But a 2.8 porting guide for example, shouldn't point to collections modules. so what do we do with them all? 15:18:56 options seem to be: 15:19:07 1 - remove the links entirely and just have text 15:19:22 2 - hardcode the links directly with URLs to the respective location in 2.8 etc 15:19:35 thoughts? 15:19:38 for anyone who is new to Ansible docs, the Porting Guides provide help for users who are upgrading - see http://docs.testing.ansible.com/ansible/devel/porting_guides/porting_guides.html 15:20:20 the entries often describe changes to modules . . . at least, for Classic Ansible versions, the entries in the Porting Guides have often pointed to module changes 15:20:43 ...and we keep porting guides up... for...ever... so this goes all the way back to ansible 2.0 potentially. At last check, there were 590? of these links, though not all are in porting guides. Some can be replaced with collection links 15:20:56 #link http://docs.testing.ansible.com/ansible/devel/porting_guides/porting_guides.html 15:21:24 #info module links in old porting guides will need some kind of fix when all the modules move to a new collection location. 15:21:31 I think if we're going to modify all of those links, we should make them point to the versions they refer to 15:21:43 so a hard url link? 15:21:49 by which I mean, the 2.8 porting guide module references should point to the 2.8 module docs 15:22:26 could we use some kind of variable? 15:22:47 do we have any plan to ever remove old releases from the docsite? I think we have down to 2.4 still published. So those links would still work, so long as we don't decide to delete the old docs 15:23:18 off the top of my head I don't know of a way to include a coded variable into an rst file. But some smart person might know how 15:23:45 I believe we will keep the old docs published for a long time 15:23:46 but if someone does, then that would work down to 2.5 at least I think, because the theme conf.py file includes a version variable 15:24:05 I think that's enough 15:24:19 if someone is trying to upgrade from 2.2 to 2.4, they can do a little extra legwork 15:24:42 #info could use some help to figure out a way to have a variable in the url in .rst that picks up the version from the conf.py file and inserts it. That way we can make the same fix to all versions of the docs and backport cleanly 15:25:29 #agreed we should use the urls to replace the internal xrefs for modules in porting guides. (e.g. 2.8 porting guide use 2.8 based module urls, etc) 15:25:35 if folks have other ideas for handling the Porting Guide links, please chime in on this channel at any time! 15:26:07 we've got five minutes left . . . 15:26:28 alas I must depart for my next meeting 15:26:32 thanks all 15:26:37 I always want to use the classic line from Car Talk . . ."Well, you've wasted another perfectly good hour in the DaWGs meeting" 15:26:40 thanks cbudz 15:26:45 thanks cbudz 15:26:49 hahaha! 15:27:08 we start with a short agenda, yet manage to fill the hr with interesting discussion! 15:27:21 They had such infectious laughs on that show 15:27:28 for those who are not familiar with Car Talk, it's a long-running radio show about "Cars, car repair, and (duh) this week's puzzler" 15:27:46 practical advice mixed with humor 15:28:09 and they always ended it with "Well, it's happened again, you've wasted another perfectly good hour listening to Car Talk." 15:28:57 all right, two minutes left 15:29:11 I'm gonna call it and give everyone those two minutes for a biobreak before their next meetings! 15:29:32 thanks cbudz gundalow kmaxwell samccann felixfontein and all the lurkers! 15:30:05 add agenda items for next week, and do whatever you can to get the PR count down before `devel` freezes March 2nd! 15:30:08 #endmeeting