14:31:48 <samccann> #startmeeting Docs Working Group aka DaWGs 14:31:48 <zodbot> Meeting started Tue Jan 7 14:31:48 2020 UTC. 14:31:48 <zodbot> This meeting is logged and archived in a public location. 14:31:48 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:31:48 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:31:48 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs' 14:32:00 <samccann> oo acozine ! sorry didn't mean to start w/o ya 14:32:13 <acozine> go for it 14:32:14 * samccann passes FearlessLeader baton to acozine 14:32:24 * acozine passes it right back again 14:32:28 <samccann> AAHAHAHA 14:32:32 <samccann> hot potato!! 14:32:36 <bcoca> yo dawgs! 14:32:43 <samccann> meanwhile, who's around for hot potato dawgs fun! 14:33:01 <samccann> welcome bcoca 14:33:16 <cbudz> present 14:33:30 <samccann> chair acozine cbudz bcoca 14:33:39 <samccann> #chair acozine cbudz bcoca 14:33:39 <zodbot> Current chairs: acozine bcoca cbudz samccann 14:34:02 <bcoca> i have overlaping meetings, so will be in/out 14:34:25 <cbudz> same for me starting @ 10am EST 14:34:29 <samccann> anyone else around? felixfontein cyberpear ? 14:34:53 <samccann> Let's start with... 14:35:02 <samccann> #topic Status Updates 14:35:43 <acozine> I can give a status update 14:35:48 <samccann> I can start - still poking at the search beast, trying to get us to one search option ( currently we have two). I am having problems with faceted search (the ability to select which version of Ansible docs you wanna search on). I have a support ticket open 14:35:56 <samccann> on to you acozine 14:36:17 <acozine> I'm working on revising the "re-use" sections of the User Guide 14:36:52 <acozine> including the page on Roles and (because I couldn't finish the Roles material without testing it . . .) the page on Tags 14:37:20 <acozine> anyone who wants a sneak preview can build the docs from . . . . 14:37:24 * acozine looks for branch 14:37:46 <acozine> https://github.com/acozine/ansible/tree/user_guide_reuse 14:38:08 <acozine> yesterday I thought it would be ready to review today, but then I got bogged down on the Tags page 14:39:03 <acozine> when it's ready for a PR I will post it here 14:39:15 <samccann> #info Reuse section of user guide being revamped by acozine 14:39:25 <acozine> I'll need a bunch of feedback on the Includes vs. Imports section 14:39:46 <samccann> #link https://github.com/acozine/ansible/tree/user_guide_reuse If you want to give it a try. PR will come once Tags page gets more docs love 14:40:10 <samccann> #info will need deep reviews of Includes vs Imports section 14:40:52 <acozine> cbudz: do you have an ansible-docs-related update? 14:40:56 <samccann> #info Search facets still not working on swiftype search option. Opening a support ticket for help. (Trying to trim us down to one site search) 14:42:47 <acozine> looks like cbudz has gotten distracted 14:42:51 <samccann> any other status updates before we move on? 14:43:40 <samccann> #topic Galaxy Docs 14:44:05 <cbudz> I'm working on updating the collections documentation based on suggestions in issue#60282 14:44:05 <samccann> Doesn't look like we have mrproper here, but this relates to how we handle doc updates for Galaxy 14:44:29 <samccann> thanks cbudz 14:44:34 <cbudz> in addition to tracking the work samccann brought to my attention before break 14:44:55 <samccann> heh glad someone remembered, cuz i'm drawing a blank 14:45:00 <cbudz> https://github.com/ansible/ansible/pull/65961 14:45:42 <samccann> ok back to galaxy docs 14:45:59 <samccann> #link https://github.com/ansible/galaxy/issues/2182 14:46:58 <samccann> #info - galaxy documentation on https://galaxy.ansible.com/docs/ needs updating, but do we update there or wait for galaxy upstream decisions? 14:47:54 <acozine> I would prefer to see the Galaxy docs published to docs.ansible.com/galaxy/, I think 14:47:55 <samccann> So the gist of it is, we have a separate docsite for galaxy right now, and a separate repo that is tied to the galaxy website/project itself. 14:48:27 <samccann> agreed, but as I recall, we were in a holding pattern on making that decision based on a higher level 'what's next for galaxy' decision, right? 14:48:44 <samccann> or maybe I just have holiday tinsel still between my ears :-) 14:48:47 <acozine> and keeping the docs in the same repo as the code they describe has served us well for Ansible core 14:49:28 <acozine> samccann: I think you are correct, but my brain is not yet fully back from the holidays 14:49:32 <bcoca> that is something you need to talk with galaxy team 14:49:34 <samccann> yep. but what's next for that repo? And how do we in the meanwhile handle things like the doc issue above? 14:50:41 <acozine> those are very good questions 14:50:54 <acozine> right now I don't have good answers 14:51:16 <samccann> do we have ideas on how to move things forward to get some answers? 14:52:10 <samccann> I do have a galaxy migration plan out for review, but it got silence before the break. I can poke the beast again, but I wonder if I'm barking up the wrong tree, or if there are other decisions being debated so I just need to cool my heels for another month or so 14:52:13 <acozine> for this specific case (documentation about how to test collections), we can develop the material on the Collections Dev page on the ansible core docs 14:52:41 <acozine> since it's not tied to the Galaxy (or AH) user interface 14:53:18 <acozine> but yes, I think it's time to poke the beast again about the future of documentation for Galaxy 14:53:45 <acozine> you and i can each get a poker ;-) 14:54:20 <samccann> so reading the issue, it seems like the tests are run on galaxy itself, right? 14:54:37 <acozine> I don't think Galaxy tests anything 14:54:45 <samccann> so while we could document how to run those tests locally (assuming that's an option)? 14:54:48 * samccann reads it again 14:55:35 <samccann> ah ok. so it's probably something triggered by the ansible-galaxy cli command? 14:55:43 <acozine> I think what mrproper is saying is, he has downloaded someone else's collection, and when he tries to use it, he gets errors, but the errors don't show up when he runs `ansible-test` 14:57:20 <samccann> what does `ansible-test` do? I thought that was something a developer uses, not a collection user? 14:57:22 <bcoca> is the collection of content that already exists in core? 14:57:33 <acozine> could be a version mismatch, I guess 14:57:39 <bcoca> samccann: we are 'productizing' ansible-test so it can be used to verify collections 14:57:51 <bcoca> could be many things, just dont think its a docs issue 14:57:53 <samccann> verify for a user? 14:57:57 <acozine> bcoca: we don't know which collection, specifically 14:58:24 <bcoca> one thing it might be if the collection is of existing code in core, ansible-test is 'passing' with the core copy and not the collection itself 14:58:33 <bcoca> ^ reason i created ansible-minimal for testing 14:58:47 <bcoca> as it removes most plugins from core to not taint the tests 14:58:57 <acozine> it's too bad mrproper isn't here to fill in the details 14:59:15 <samccann> ok so from the sounds of it, we need more detail in the issue to know what exactly went wrong, on what... and then we can decide how to document to help others in a similar boat 14:59:23 <bcoca> ansible-test is supposed to be available to content authors, but it is also something consumers will want to use to 'verify' the collections 15:00:10 <samccann> #info we can document https://github.com/ansible/galaxy/issues/2182 in our collections docs on docs.ansible.com once we have more detail on what was being tested and what went wrong etc. 15:00:11 <acozine> yeah, I think the request for docs is a good one, but we may not know what the correct procedure is yet - this issue may really help us 15:00:44 <acozine> ah, looking at it again, it looks like he's trying to take something out of core and put it in a collection . . .? 15:00:56 <bcoca> ansible-test isn't finished yet, afaik, so a bit premature, though the sooner we have docs, the more people can use/test/debug/perfect cycle ... 15:01:24 <acozine> he says `I cannot find what command to run to discover these errors before I upload` 15:01:24 <bcoca> acozine: ok, so that is something i would point content authors to ansible-minimal for 15:01:46 <acozine> samccann: I think you were right, Galaxy must be doing some kind of linting 15:02:39 <samccann> ok so for this issue, I think we've beaten it as much as we can right now w/o more info from mrproper. I'll ask in the issue for more details etc 15:03:28 <samccann> anything else here before we move on? 15:04:38 <bcoca> galaxy does a buch of diff checks, i can point you to code in importer, dont know all top of my head 15:04:58 <samccann> sure drop a pointer here or in the issue when you get a chance thanks bcoca 15:05:22 <samccann> #topic Issues and PRs 15:05:29 <bcoca> https://github.com/ansible/galaxy/tree/devel/galaxy/importer/ <= see linter(yamllint) and tests dirs, those are what get used on import 15:06:04 <samccann> #link https://github.com/ansible/galaxy/tree/devel/galaxy/importer/ <= see linter(yamllint) and tests dirs, those are what get used on import into galaxy 15:06:06 <samccann> thanks! 15:06:43 <samccann> Meanwhile, we are at 231 on the open docs issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs that's inched up a bit since before the holiday break. 15:07:03 <samccann> Feel free to grab an issue and create a PR for it! :-) help always wanted in that arena. 15:07:14 <acozine> I merged at least one PR that addressed 65989 15:07:22 <acozine> not sure it got all the instances, but I will check 15:07:28 <acozine> and if it did, I'll close the issue 15:07:48 <samccann> kewl! 15:08:28 <acozine> ah, we should draw attention to the Jinja2 => Jinja renaming thing 15:08:35 <acozine> samccann: can you do your IRC magic? 15:08:53 <acozine> the docs issue is https://github.com/ansible/ansible/issues/66163 15:09:07 <samccann> #topic Jinja2 is becoming Jinja 15:09:17 <samccann> #link https://github.com/ansible/ansible/issues/66163 15:09:35 <samccann> mostly it sez what it means... but it means at some point we have to update all the jinja2 references in the docs 15:10:02 <samccann> So we are keeping an eye on that issue to determine when the docs changes need to happen 15:10:23 <acozine> I have to run - see folks later! 15:10:34 <samccann> bye acozine 15:10:44 <acozine> o/ 15:11:05 <samccann> #topic Docs PRs 15:11:55 <samccann> #info We have 97 open docs PRs thanks to acozine working her little holiday magic to keep them down below 100. 15:11:58 <samccann> https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs 15:12:31 <samccann> We were keeping them down around 75 (three github pages) but things have gotten difficult over the past few months, trying to keep that number down. 15:12:58 <samccann> Please do go in and review, leave comments, or approve PRs as you see fit. Every little bit helps move them along to eventual merging. 15:13:32 <samccann> #topic Open Floor 15:13:49 <samccann> Anyone have anything they want to bring up in docs land? 15:14:08 <samccann> oo one other thing! 15:14:13 <samccann> #topic broken links 15:15:10 <samccann> I ran a link checker (blc if anyone is curious) ... we have something over 500 broken links in the ansible docs, most in the modules themselves. I fixed a dozen or so, but that'll be my I'm braindead task over the long haul 15:15:37 <samccann> #info used blc locally against a build to find and fix some broken links (and we have a fair few) 15:16:15 <samccann> I don't recommend this approach yet for the average DaWG. But I am hoping we can eventually find something that works well and will help us trim down those broken links 15:16:26 <samccann> and back to 15:16:31 <samccann> #topic Open Floor 15:16:35 <samccann> anyone have anything else? 15:17:38 <samccann> okay time to call it then 15:17:46 <samccann> #endmeeting