14:31:32 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:32 <zodbot> Meeting started Tue Feb 18 14:31:32 2020 UTC.
14:31:32 <zodbot> This meeting is logged and archived in a public location.
14:31:32 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:32 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:32 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:40 * samccann waves
14:31:53 <acozine> hello, good morning, good afternoon, good evening!
14:31:58 <acozine> #chair samccann
14:31:58 <zodbot> Current chairs: acozine samccann
14:32:05 <acozine> who is around?
14:33:03 <felixfontein> I'm around, but only for ~3 minutes ;)
14:33:06 <acozine> andersson007_: baptistemm cbudz cyberpear dag felixfontein kmaxwell madonius mrproper Pilou shaps tributarian you folks ready to chat docs?
14:33:19 <acozine> felixfontein: that's very efficient of you!
14:34:11 <kmaxwell> I am pleased to be here, but maybe don't have a lot to say :-)
14:34:24 <acozine> welcome kmaxwell
14:34:34 <acozine> #chair kmaxwell
14:34:34 <zodbot> Current chairs: acozine kmaxwell samccann
14:34:44 <cbudz> *waves* I'm here, just wrapping up a troubleshooting session with another writer at the moment
14:34:53 <acozine> we generally like to have as much furniture around the place as possible ;-)
14:34:58 <acozine> #chair cbudz
14:34:58 <zodbot> Current chairs: acozine cbudz kmaxwell samccann
14:35:08 <acozine> looks like a light agenda today
14:35:18 <acozine> #topic how to add agenda items
14:36:05 <acozine> oof, I'm having network issues
14:36:15 <acozine> we started a new GitHub issue for the DaWGs agendas for 2020
14:36:45 <acozine> here's a link to the issue: https://github.com/ansible/community/issues/521
14:36:58 <acozine> the last comment is always the upcoming meeting's agenda
14:37:19 * gundalow waves
14:37:28 <gundalow> I'm actually here this week
14:37:31 <acozine> #chair gundalow
14:37:31 <zodbot> Current chairs: acozine cbudz gundalow kmaxwell samccann
14:37:38 <acozine> gundalow: awesome!
14:37:52 * gundalow sits
14:37:59 <acozine> so . . . the agenda is open to all - anyone can add an item to it
14:38:28 <acozine> just add a comment to the issue - you can link to PRs and issues on any GitHub repo
14:39:02 <acozine> so if you want feedback or help on anything docs-related, feel free to add it to the agenda
14:39:08 <kmaxwell> agenda is linked from the wiki, which is super handy if you're struggling to find it
14:39:37 <acozine> kmaxwell: ah, excellent - is the link updated for the new 2020 agenda?
14:40:02 <kmaxwell> the link uses labels so is always up to date (I think)
14:40:31 <kmaxwell> if you're searching for it manually remember it is in the ansible/community repo
14:41:24 <kmaxwell> rather that the ansible/ansible repo, which is where you might start your search if you're naive like me :-)
14:41:44 <kmaxwell> s/rather that/rather than/
14:42:02 <acozine> kmaxwell: we have enough issues in the ansible/ansible repo without opening ones we know we will never close ;-)
14:42:48 <gundalow> :)
14:43:00 <kmaxwell> :)
14:43:45 <acozine> 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 <acozine> someday I will learn all the right IRC commands
14:44:15 <gundalow> `#info foo`
14:44:27 <acozine> ah, thanks gundalow
14:44:59 <acozine> #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 <samccann> #info anyone can add to the agenda at https://github.com/ansible/community/issues/521
14:45:11 <samccann> haha sorry... slow on the uptake today
14:45:15 <acozine> heh, now it will really stand out!
14:45:30 <samccann> see we really MEAN IT!
14:45:34 <acozine> all right, first actual agenda item is status updates
14:45:35 <acozine> heh
14:45:42 <acozine> #topic quick status
14:46:04 <samccann> Gotta say your idea of putting the broken links in issues and asking for help worked like a charm!
14:46:18 <acozine> oh, excellent!
14:46:24 <samccann> #info -community help on docs broken links has been fantastic!  most issues are closed already!
14:46:43 <acozine> thanks to everyone who stepped up!
14:47:09 <acozine> we are back under 75 open PRs marked `docs` on the ansible/ansible repo
14:47:28 <acozine> https://github.com/ansible/ansible/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Adocs+
14:47:46 <acozine> there are still some that could use reviews, especially on the first page
14:48:13 <acozine> a lot of the older ones combine code and docs, and it's tough for the docs team to merge them
14:48:27 <samccann> #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 <acozine> 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 <acozine> gundalow: do you want to talk about the timeline for the Great Module Migration?
14:49:51 <gundalow> Sure, thanks
14:49:58 <gundalow> #topic Collections
14:50:29 <gundalow> #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 <gundalow> #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 <samccann> 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 <cbudz> gundalow I have some collections FAQ info that came in last week I'll see how i can add to that
14:53:34 <samccann> 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 <gundalow> 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 <gundalow> Yup, this is upstream (Community) only, so no mention of Automation Hub, Ansible Automation Platform, etc
14:55:09 <cbudz> 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 <gundalow> 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 <gundalow> -typos
14:55:46 <gundalow> 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 <samccann> gundalow - is it worth putting a link from 'developing collections/using collections' in docs to that readme once it's merged?
14:56:26 <gundalow> That's a great idea, I'll do that
14:57:56 <acozine> in the last couple of weeks, we've talked about sharing the dates for the transition to Collections
14:58:07 <acozine> we have more information now, so I'm going to post that here
14:58:29 <acozine> remember that if the core team runs into challenges, these dates may change
14:59:23 <acozine> #info preliminary start date for the Collections Transition: ansible/ansible devel branch will freeze on March 2nd for the transition
15:00:25 <acozine> so if you have things you'd like to see merged into the main repo, please prioritize them NOW
15:00:27 <gundalow> 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 <acozine> the rest of this week and all of next week . . . that's all the time we have to get things merged
15:01:09 <samccann> but no new modules will be accepted
15:01:12 <gundalow> 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 <gundalow> samccann++
15:01:34 * gundalow needs to drop off now, Thanks
15:01:39 <gundalow> Feedback on the PR welcome
15:01:42 <acozine> #info we have already instituted a No New Modules policy
15:01:53 <samccann> jinx! waas just typing that
15:01:53 <acozine> all new modules must be developed in a collection
15:01:55 <acozine> heh
15:02:04 <acozine> gundalow: thanks!
15:05:11 <acozine> 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 <acozine> by opening the floor early
15:05:34 <acozine> not that the floor is ever really closed in a DaWGs meeting ;-)
15:05:43 <acozine> #topic open floor
15:06:06 <acozine> any questions (about collections or docs or anything else, really)?
15:06:27 <acozine> suggestions, ideas, PRs that need attention, issues that piqued your interest, etc.?
15:06:33 <samccann> yeah feel the same about opening the floor earlier than we usually do
15:07:57 <samccann> i do have a Great Module Migration topic to discuss
15:08:09 <cbudz> I have a quick Q about an issue
15:08:11 * samccann waits a bit in case someone else has something
15:08:24 <acozine> cbudz: excellent, what's the question?
15:08:38 <cbudz> I grabbed this yesterday and started working on it: https://github.com/ansible/ansible/issues/65805
15:09:13 <acozine> great!
15:09:31 <cbudz> 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 <cbudz> 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 <acozine> 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 <acozine> updating those has been on the "big list of docs to-do" for a long time
15:11:18 <samccann> 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 <cbudz> Ok, that's good to know
15:11:43 <acozine> current docs are at https://molecule.readthedocs.io/en/latest/
15:12:23 <acozine> I would love to see those docs "brought into the fold" on docs.ansible.com
15:12:30 <acozine> along with the galaxy docs
15:13:15 <acozine> cbudz: for some background, Molecule was a community project that RH/Ansible adopted
15:14:00 <samccann> 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 <acozine> oh, right, I'd forgotten that
15:14:37 <acozine> that will be awesome!
15:14:53 <samccann> #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 <cbudz> I'll snoop around and please feel free to share info if it comes along
15:15:35 <samccann> will do cbudz
15:17:20 <acozine> other questions, concerns, suggestions, ideas?
15:17:43 <samccann> I had one
15:17:53 <samccann> #topic What to do with module links in porting guides
15:18:09 <acozine> oof, yes, we need to work on that
15:18:29 <samccann> 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 <samccann> 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 <samccann> options seem to be:
15:19:07 <samccann> 1 - remove the links entirely and just have text
15:19:22 <samccann> 2 - hardcode the links directly with URLs to the respective location in 2.8 etc
15:19:35 <samccann> thoughts?
15:19:38 <acozine> 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 <acozine> 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 <samccann> ...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 <samccann> #link http://docs.testing.ansible.com/ansible/devel/porting_guides/porting_guides.html
15:21:24 <samccann> #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 <acozine> 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 <samccann> so a hard url link?
15:21:49 <acozine> by which I mean, the 2.8 porting guide module references should point to the 2.8 module docs
15:22:26 <acozine> could we use some kind of variable?
15:22:47 <samccann> 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 <samccann> 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 <acozine> I believe we will keep the old docs published for a long time
15:23:46 <samccann> 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 <acozine> I think that's enough
15:24:19 <acozine> if someone is trying to upgrade from 2.2 to 2.4, they can do a little extra legwork
15:24:42 <samccann> #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 <samccann> #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 <acozine> if folks have other ideas for handling the Porting Guide links, please chime in on this channel at any time!
15:26:07 <acozine> we've got five minutes left . . .
15:26:28 <cbudz> alas I must depart for my next meeting
15:26:32 <cbudz> thanks all
15:26:37 <acozine> 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 <samccann> thanks cbudz
15:26:45 <acozine> thanks cbudz
15:26:49 <samccann> hahaha!
15:27:08 <samccann> we start with a short agenda, yet manage to fill the hr with interesting discussion!
15:27:21 <cbudz> They had such infectious laughs on that show
15:27:28 <acozine> 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 <acozine> practical advice mixed with humor
15:28:09 <acozine> 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 <acozine> all right, two minutes left
15:29:11 <acozine> I'm gonna call it and give everyone those two minutes for a biobreak before their next meetings!
15:29:32 <acozine> thanks cbudz gundalow kmaxwell samccann felixfontein and all the lurkers!
15:30:05 <acozine> 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 <acozine> #endmeeting