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