14:32:27 <samccann> #startmeeting Docs Working Group aka DaWGs
14:32:27 <zodbot> Meeting started Tue Nov 12 14:32:27 2019 UTC.
14:32:27 <zodbot> This meeting is logged and archived in a public location.
14:32:27 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:32:27 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:32:27 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:32:37 <samccann> Who's around to talk the docs?
14:33:45 <samccann> gundalow alongchamps felixfontein Xaroth bcoca ??
14:34:39 <bcoca> i have 3 conflicting meetings , but will try
14:35:24 * acozine waves
14:35:38 * samccann starts tossing furniture around
14:35:44 <samccann> #chair bcoca acozine
14:35:44 <zodbot> Current chairs: acozine bcoca samccann
14:36:02 <samccann> Well, we can start of slow.. with...
14:36:11 <samccann> #topic Moving Galaxy docs to docs.ansible.com
14:36:20 <acozine> andersson007_: cyberpear jhawkesworth shaps you folks around?
14:36:47 <samccann> For a bit of background - the galaxy docs live on galaxy.ansible.com/docs today. Kind of in their own world so to speak.
14:37:23 <andersson007_> Hey acozine !
14:37:26 <samccann> We're bringing them 'into the fold' on docs.ansible.com. The galaxy docs repo stays were it is (ansible/galaxy) but the generated docs are now picked up by docs.ansible.com
14:37:44 <acozine> hey andersson007_, welcome!
14:37:53 <andersson007_> Thabks!
14:38:07 <samccann> hey! more furniture!!
14:38:20 <acozine> \o/
14:38:20 <samccann> #chair andersson007
14:38:20 <zodbot> Current chairs: acozine andersson007 bcoca samccann
14:38:42 <samccann> So the galaxy docs are at https://docs.ansible.com/ansible-galaxy/latest/
14:39:41 <samccann> The move isn't quite complete. Well that url is, but there are other bits and bobs on docs.ansible.com to point to that site that still needs to be done, and eventually updating the galaxy ui to point there etc
14:40:11 <acozine> the old galaxy docs were/are a backwater, there's no good way to move back and forth between docs and the Galaxy UI; moving them to docs.ansible.com makes this a bit easier
14:40:14 * alongchamps waves
14:40:14 <samccann> so please poke around that url etc and let us know if you see any problems. We'd like to 'go live' wit that asap
14:40:24 <acozine> welcome alongchamps!
14:40:29 <samccann> #chair alongchamps
14:40:29 <zodbot> Current chairs: acozine alongchamps andersson007 bcoca samccann
14:40:48 <samccann> got enuf chairs now for a small DaWGs dinner party  woot!
14:41:14 <alongchamps> woot
14:42:07 <samccann> A question I have for the hive mind - I can't think of a way to do 'redirects' from galaxy.ansible.com/docs to docs.ansible.com/ansible-galaxy/latest.  Not sure what to do with the 'old docs' so to speak.
14:42:37 <samccann> I was thinking of just 'leaving' them hanging there, but then google searches currently find that stuff so... dilema dilema
14:43:07 <samccann> I can't easily update the old docs with stubs pointing to the new docs, cuz it's all the same source in github.
14:43:17 <acozine> hmmmm, we could just put a single page on galaxy.ansible.com/docs that says "the docs have moved to . . . " with a link
14:43:39 <acozine> do we know how they currently publish the docs to that location?
14:43:42 <samccann> yes, but that still leaves google pointing to the old docsite so to speak for deeper links
14:44:12 <acozine> true . . .
14:44:13 <samccann> and no, I dunno how that gets published at the moment. it's under the auspices of the galaxy team. They are very VERY busy bees this week so didn't wanna bring it up yet. It's not super urgent
14:44:59 <acozine> if we update the source with a canonical URL that points to docs.ansible.com and then publish to both places, will Google figure it out?
14:45:05 <samccann> I'm thinking if we just let the old docsite linger, it's kind of like :orphan: pages on docs.ansible.com  - they are still there, but eventually people and google figure it out
14:45:50 <alongchamps> I've been doing some googling recently for VMware modules and several of the pages Google had indexed were taking me to 2.5 even if a newer version was enabled
14:45:50 <samccann> ooo that might work acozine!  worth a try anyway.  I still have the old theme in place (even on docs.ansible.com). That's a future task, to use git submodule to share the sphinx theme basics between the two if possible
14:46:05 <alongchamps> so I'm not sure if there's a good way to get Google to update its search results
14:46:39 <acozine> the canonical URL approach worked pretty well for moving search results on the main Ansible docs over to `latest`
14:46:52 <acozine> it's not perfect, but it's decent
14:46:55 <samccann> yep.
14:47:26 <samccann> there aren't a ton of hits on galaxy docs (yet) compared to ansible docs, but I expect that might grow now that collections are The Big Thing
14:48:08 <acozine> and I suspect that the remaining results that point to specific versions may be related to highly-trafficked blog posts written at the time those versions were released
14:48:27 <alongchamps> that could be it
14:48:49 <acozine> but most searches for Ansible now return `latest` and that is a big change from 18 months ago
14:50:32 <samccann> ok. again, please do poke at the new galaxy location and let us know if you see problems etc.
14:50:39 <samccann> but... moving on... :-)
14:51:09 <samccann> #topic Docs Issues
14:51:24 <samccann> #link https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs
14:51:41 <samccann> we are at 227 open docs issues.  But there are some `easyfix` ones in there
14:51:58 <acozine> that's not as bad as I expected, actually
14:52:13 <samccann> #link https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs+label%3Aeasyfix
14:52:40 <acozine> we're almost back to 9 pages' worth
14:52:54 <acozine> which probably means we have a LOT more PRs
14:53:10 <samccann> anyone up for grabbing this one? https://github.com/ansible/ansible/pull/64645
14:53:29 <samccann> it's an easy one I think - a couple of modules are missing their shortdescription.
14:54:35 <acozine> hm, are we looking at the same issue? I don't see a list of modules . . . ?
14:54:59 <acozine> the one linked above is about recommending storing playbooks in a subfolder called `plays`
14:55:01 <samccann> dang.. fatfingered the link
14:55:34 <samccann> this is the correct link = https://github.com/ansible/ansible/issues/64654
14:56:42 <acozine> ah
14:57:27 <acozine> interesting issue, I wonder why we haven't been catching that in the buld?
14:57:34 <acozine> s/buld/build/g
14:57:40 <samccann> good question.
14:58:55 <acozine> it's weird, it seems like an obvious thing we all should have noticed . . .
14:59:14 <acozine> #chair
14:59:14 <zodbot> Current chairs: acozine alongchamps andersson007 bcoca samccann
14:59:52 <acozine> has anybody seen the error listed in https://github.com/ansible/ansible/issues/64654?
15:01:03 <samccann> nope but I just reproduced it
15:01:57 <samccann> hmm and `win_template` does have a short description, so maybe it's not  the simple fix we thought
15:02:19 <acozine> curiouser and curiouser, as Alice would say
15:04:12 <acozine> here's the current published docs for that module: https://docs.ansible.com/ansible/devel/modules/win_template_module.html
15:05:05 <acozine> does the short description show up on the docsite?
15:05:56 * felixfontein waves
15:06:01 <acozine> ah, it's the second part of the title
15:06:08 <acozine> felixfontein: welcome!
15:06:15 <acozine> #chair felixfontein
15:06:15 <zodbot> Current chairs: acozine alongchamps andersson007 bcoca felixfontein samccann
15:06:32 <acozine> so yeah, the win_template module does have one
15:06:44 <samccann> there is no shortdescription in the source for win_template https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/windows/win_template.py#L14
15:07:47 <acozine> is it in the shared doc fragment?
15:08:12 <samccann> yeah. I can't for the life of me remember where the docfragments moved to tho... can you?
15:08:51 <samccann> my guess is shortdescription from a docfragment doesn't work with `ansible-doc -l` but need to see what's in the shared fragment to be sure
15:09:49 <acozine> yeah, it's there: https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/template_common.py#L14
15:10:15 <acozine> (I had to grep the codebase to remind myself where those fragments live . . .)
15:11:15 <acozine> so it's a reasonable question to ask - is the error in `ansible-doc -l` important? should we move those short descriptions out of the shared snippet and into the main files?
15:11:26 <samccann> yep so the two that have the 'missing short description' both share the same docfragment
15:12:07 <acozine> that makes sense
15:12:24 <samccann> well there's two ways of looking at it now -as a doc issue (and thus move the short description out of the docfragment).. .or a coding issue, as ansible-doc -l doesn't work if the shortdescription is in a doc fragment
15:12:36 <acozine> true
15:13:05 <samccann> my nickel - just fix it as a doc issue. I'm thinking of the thousands of modules we have, only two got 'clever' with the docfragment like this.
15:13:25 <acozine> heh, true
15:13:58 <acozine> and we have other modules that have a "windows equivalent", so we must not have done this on those
15:14:13 <acozine> I'll put a note on the issue
15:14:45 <samccann> ok kewl
15:14:59 <samccann> shall we open the floor?
15:15:49 <samccann> #topic Open Floor
15:15:59 <samccann> what's on your minds, folks?
15:16:51 <samccann> burning questions? brilliant ideas? problems with this or that in docs lands that you want to discuss?
15:17:41 <acozine> I have an apology to make - I said I would merge Pilou's PR a week or two ago, and I have not gotten to it
15:18:15 <samccann> hashtag topic true confessions
15:18:43 <acozine> heh, and his GitHub user name has an odd character in it that I can't remember
15:18:49 <acozine> so I can't find it
15:18:54 <acozine> drat
15:20:52 <samccann> hmm github needs a way to find every PR you are subscribed to.
15:20:59 <acozine> found it!
15:21:10 <samccann> \o/
15:21:21 <acozine> https://github.com/ansible/ansible/pull/62778
15:21:53 <acozine> so this is one of those PRs that fails our CI system because we're adding docs for a feature that has existed for a long time but was never documented
15:22:08 <acozine> and the test suite thinks it should be marked `added in 2.10`
15:22:34 <samccann> ah ok yeah remember seeing that one
15:23:15 <acozine> `version_added for new option (cmd) should be '2.10'. Currently StrictVersion ('0.0') (75%)`
15:24:08 <acozine> I think the addition is very useful
15:24:10 <Pilou> acozine: apology not needed :)
15:24:35 <acozine> I hate letting good contributions go stale!
15:25:20 <acozine> anyway, it's now telling me the CI is stale, which leads to an interesting philosophical question . . . is it important to re-run the test suite when we know it will fail?
15:25:38 <acozine> I suppose it might fail in other ways if someone added a test in the interim
15:26:15 <samccann> yeah probably worth a rerun just in case
15:26:53 <acozine> heh, I guess since it's a special case, we should be sure we follow protocol in all other ways
15:27:04 * acozine kicked off a fresh test run
15:27:32 <acozine> hey, Shippable is already running it! I guess it's having a quiet day
15:27:39 <acozine> no "status: waiting" today
15:28:02 <samccann> heh
15:28:22 <samccann> meanwhile just notices docs PRs are down to 93!
15:28:23 <acozine> thanks again Pilou, it's a good addition
15:28:46 <samccann> which is a relative bit of excitement, since our goal is < 75  but still.. it's been over 100 for a while now
15:28:53 <acozine> samccann: that is awesome,
15:29:41 <acozine> oops, the meeting is almost over
15:29:52 <acozine> oh, speaking of PRs . . .
15:30:01 <acozine> this week is the next Big PR Review Day
15:30:05 <acozine> This Thursday
15:30:41 * acozine searches for more information
15:31:08 <samccann> https://github.com/ansible/community/issues/407
15:31:17 <samccann> #topic Big PR Review Day
15:31:29 <samccann> #info this Thursday in the ansible-community channel
15:31:33 <samccann> #link https://github.com/ansible/community/issues/407
15:31:53 <acozine> samccann: thanks!
15:32:06 <samccann> bring your fav PRs and get some help getting them merged/reviewed/ etc
15:32:24 <samccann> or show up and help move some others along! it's a PR Party!
15:33:07 <acozine> bring your expertise and your curiosity - everyone welcome
15:33:29 <samccann> and this is all PRs btw... though we hope to get some docs love going there as well
15:34:11 <acozine> hope to see you all there!
15:34:11 <gundalow> :)
15:34:45 <acozine> thanks gundalow bcoca alongchamps andersson007_ felixfontein Pilou
15:34:57 <acozine> see you around the internet!
15:35:10 <samccann> #chair Pilou
15:35:10 <zodbot> Current chairs: Pilou acozine alongchamps andersson007 bcoca felixfontein samccann
15:35:18 <samccann> tee hee... had to get that last minute chair toss in there!
15:35:31 * samccann has simple joys in life
15:35:33 <acozine> heh, nice on!
15:35:37 <acozine> s/on/one/g
15:35:52 * acozine is losing ability to spell/type . . . needs more tea
15:36:03 <acozine> thanks everybody!
15:36:06 <acozine> #endmeeting