15:30:35 <acozine> #startmeeting Docs Working Group
15:30:35 <zodbot> Meeting started Tue Feb 12 15:30:35 2019 UTC.
15:30:35 <zodbot> This meeting is logged and archived in a public location.
15:30:35 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:30:35 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:30:35 <zodbot> The meeting name has been set to 'docs_working_group'
15:30:53 <acozine> #chair samccann dag alongchamps
15:30:53 <zodbot> Current chairs: acozine alongchamps dag samccann
15:31:04 <acozine> who else is around?
15:31:33 <kmaxwell> Hello, my first time here
15:31:40 <acozine> welcome, kmaxwell!
15:31:48 <acozine> #chair kmaxwell
15:31:48 <zodbot> Current chairs: acozine alongchamps dag kmaxwell samccann
15:31:57 <kkao07> present
15:32:19 <acozine> making you a chair means you get to record things for posterity, but feel free to observe if that's more comfortable for you
15:32:27 <acozine> welcome kkao07
15:32:31 <kmaxwell> thank you!
15:32:34 <acozine> #chair kkao07
15:32:34 <zodbot> Current chairs: acozine alongchamps dag kkao07 kmaxwell samccann
15:33:03 <acozine> I don't know if we have anything on the official agenda today - while I look I will share some pictures of what I've been doing with my week
15:33:18 <acozine> https://photos.google.com/share/AF1QipNVkb04TQSZiYGMujzwY1MUeF0cy-yMJ6iqAIi6UmpOSNMNjMzuVr-J8PhZNiY1Aw?key=bnZhV1V6Z1dPaUd3UGhGYzVKTl9vLTJVckZhTDJn
15:33:31 <acozine> ah, winter in the upper midwestern US!
15:34:08 <samccann> that is a lot of ice in a lot of not-good places!
15:34:20 <acozine> we're calling it the Ice Palace
15:34:32 <alongchamps> bad ice, you're supposed to stay outside!
15:34:41 <dag> Ugh
15:35:52 <acozine> we just bought the place in November and were planning to renovate, but were hoping to do it a little more gradually
15:36:18 <acozine> okay, looks like we have two firm items on the agenda
15:36:33 <acozine> first one is from kmaxwell - https://github.com/ansible/ansible/pull/49798
15:36:43 <acozine> #topic PR 49798
15:37:00 <acozine> first off, thanks kmaxwell for taking the time to open a PR
15:37:24 * gundalow waves
15:37:35 <acozine> #chair gundalow
15:37:35 <zodbot> Current chairs: acozine alongchamps dag gundalow kkao07 kmaxwell samccann
15:38:05 <acozine> we have a few open PRs related to the documentation for Vault
15:38:06 <kmaxwell> I got some helpful feedback, but wanted to ask is there anything more I can do to move it along?
15:38:25 <acozine> kmaxwell: do you use vault regularly with Ansible?
15:38:42 <acozine> kmaxwell: this is the right place for that
15:39:02 <kmaxwell> Yes, more than that I've been training another team member to start working with it too
15:39:29 <kmaxwell> We're regularly looking at the docs together, which is the motivation to try & help
15:39:36 <acozine> that is awesome!
15:40:03 <acozine> I haven't used Vault in quite a while - I thought this was still true: "The password used with vault currently must be the same for all files you wish to use together at the same time."
15:40:15 <acozine> from your PR, it seems it is no longer true?
15:40:39 <kmaxwell> I think it changed in 2.4, you can definitely use multiple vaults with different passwords
15:41:17 <acozine> and if you want to use them in the same playbook, what does that look like?
15:42:00 <kmaxwell> tried to demo it in the additional information section, but maybe something like ASCII cinema would be easier to follow?
15:42:01 <acozine> I'm asking more for my own information than anything else
15:42:13 <acozine> ah, apologies, let me look again
15:42:31 <kmaxwell> Basically you label each vault with a separate ID
15:42:45 <acozine> gotcha, I see it
15:43:05 <samccann> i'm happy to give this all a try after the meeting, following kmaxwell's example in the PR. I need some vault practice anyway
15:43:21 <samccann> and if it all works as expressed in the PR, I can merge?
15:43:51 <acozine> samccann: yes, i think it's okay to merge, I'm wondering if we can use the momentum (and the testing time) to verify the vault docs more generally
15:43:51 <kmaxwell> gundalow was one of the people giving feedback already - hopefull that's been actioned to his satisfaction?
15:44:25 <kmaxwell> I tried to start small with this one - it was quite black and white
15:44:31 <acozine> kmaxwell: yes, the PR is good to go at the level it's at
15:45:08 <acozine> one of the things we'd like the DaWG (Documentation Working Group) to foster is greater efficiency in docs maintenance
15:45:09 <kmaxwell> I could look at the section more widely? If this is an area the core team is open to PRs for?
15:45:20 <acozine> kmaxwell: yes!
15:45:44 <acozine> and generally speaking, small chunks are a great approach
15:45:56 <samccann> acozine: okay I'll merge.
15:46:35 <gundalow> kmaxwell: yup, my comment on 49798 has been resolved
15:46:41 <acozine> if you're open to reviewing the vault docs, kmaxwell, I think we have a couple of other stale PRs that are related
15:47:48 <kmaxwell> OK will take a look, the CI unfortunately added a lot of noise to that PR, but I'll generally go with the small chunks
15:47:49 <acozine> if you want to take a look at 43993, 46423, and/or 50958
15:48:32 <acozine> kmaxwell: yes, CI has had a lot of unrelated failures recently - if you run into that again, ping us here
15:49:35 <acozine> I think your example from the Additional Information section could usefully be added to the vault page
15:49:50 <acozine> ^^^ section of your existing PR, that is
15:50:00 <kmaxwell> I don't think 46423 is about Ansible Vault, I think its Hashicorp's Vault (a different project)
15:50:16 <acozine> ah, my mistake
15:50:25 <acozine> ignore that one
15:50:29 <kmaxwell> acozine: OK well that is an easy small chunk to add
15:51:04 <acozine> any other comments/ideas/suggestions on Vault docs before we move on?
15:51:58 <kmaxwell> happy to move on, will try to come back with something based on above PRs and suggestions
15:52:09 <acozine> fantastic, thanks kmaxwell!
15:52:37 <acozine> okay, the other topic on the agenda is part of the CSS update effort
15:52:49 <acozine> #topic https://github.com/ansible/ansible/pull/49289
15:53:02 <acozine> this has been on the agenda for quite a while
15:53:15 <acozine> I mean, the general agenda of the docs team, not the meeting agenda ;)
15:53:46 <samccann> #agreed kmaxwell will dig further into vault docs and make suggestions in PRs
15:53:58 * samccann tries to keep up w/ meeting minutes
15:54:12 <acozine> thanks samccann!
15:54:30 <kmaxwell> samccann: thanks for merging!
15:55:47 <acozine> so PR 49289 is a cleanup PR - I've held off merging it so far, because part of me wanted to go back and look at all the changes we've made to that theme and figure out what we were trying to do with them and whether we could incorporate them into the theme we're actually using
15:56:17 <acozine> for background, for those who have no idea what I'm talking about . . .
15:57:04 <acozine> Back in early 2018, we did a big re-org of the documentation in conjunction with the release of Ansible 2.5, and we introduced a second Sphinx theme by mistake
15:57:53 <acozine> since then, we've made some changes to each theme, so some of the changes we thought we were making had absolutely no effect on the docsite
15:58:24 <gundalow> acozine: any ideas why you saw different results when running server vs `file:///`?
15:58:24 <acozine> any thoughts on the best way forward?
15:58:39 <samccann> could we take one section at at time of that pr and put it into the theme we are using?
15:59:00 <acozine> gundalow: nope, still no clue
15:59:06 * gundalow hopes it was a caching issue
15:59:45 <acozine> anybody willing to pull the branch and test, to see if you can recreate what i saw?
16:01:11 <samccann> I can give it a try
16:01:23 <acozine> samccann:  awesome
16:01:29 <acozine> the PR we're looking at now is just removing stuff, it doesn't add anything
16:01:43 <acozine> but we've had past PRs that made changes to the files this PR is removing
16:01:56 <acozine> and presumably those changes were motivated by something
16:02:09 <samccann> ah so the 'ultimate' goal would be to see if those past PRs are also in the theme we are using?
16:02:48 <acozine> yeah, and if not, are those changes something we want to keep?
16:02:54 <gundalow> For testing is it review some set of pages and ensuring they look the same on both versions?
16:03:02 <acozine> but at the same time, I'm open to the damn-the-torpedoes approache
16:03:07 <acozine> see https://github.com/ansible/ansible/commits/devel/docs/docsite/_themes/srtd
16:03:50 <acozine> gundalow: well, I don't think we've actually used the `srtd` theme since the re-org
16:04:07 <gundalow> ah, OK
16:04:09 <acozine> so it should look the same before and after Xaroth's PR
16:04:42 <samccann> #action samccann to test pr 49289 to try and recreate acozine's results (or not)
16:04:43 <acozine> we can ignore anything from before 2018
16:04:52 <acozine> samccann: thanks
16:05:14 <acozine> any other thoughts on this PR or on CSS more generally?
16:05:23 <samccann> so if we test and it all looks grand, we merge and then we don't have to go back and review older PRs?
16:06:07 <gundalow> acozine: needs rebase
16:06:16 <acozine> if it looks grand, we can rebase and merge, but I'd still like to do a quick look at the PRs on the non-used theme since January 2018
16:06:29 <acozine> the thing is, those changes were trying to fix something
16:06:42 <acozine> they didn't fix anything, because they were changing the wrong files
16:07:00 <acozine> but if the problems they were trying to fix still exist, we might want to fix them in the right files
16:07:09 <samccann> #agreed if it looks grand, we can rebase and merge, but  still  do a quick look at the PRs on the non-used theme since January 2018, since they were trying to fix something. See if they need to be applied to the current theme
16:08:08 <acozine> awesome
16:08:22 <acozine> any other discussion about themes, or CSS, or related thoughts?
16:08:55 <acozine> going once, going twice . . .
16:09:23 <acozine> hearing none . . . #topic open floor
16:09:27 <acozine> hrm, that didn't work
16:09:31 <acozine> #topic open floor
16:10:02 <acozine> who's got something to discuss?
16:11:03 <acozine> I have a proposal . . .
16:11:11 <samccann> propose away!
16:11:34 <acozine> I'm wondering if we can set a topic for the week
16:12:02 <acozine> set the topic today, then revisit/wind it up at next week's meeting
16:12:20 <acozine> my proposed topic is `loop` vs `with_*`
16:12:34 <acozine> I have a related open PR
16:12:43 <acozine> and there are a couple of other related open PRs
16:12:56 <samccann> I think if we can provide the topic and enough background that might be a great idea
16:13:08 <acozine> there also might be other places in the docs where we discuss loops and/or with_*
16:14:14 <samccann> so can you summarize what we are looking for in the `loop` vs with_*` debate?
16:14:23 <acozine> I can try ;)
16:14:32 * samccann still failing at irc tricks
16:14:37 <acozine> heh
16:15:35 <acozine> Ansible currently supports two different ways of looping over multiple items: the legacy `with_<filter_plugin>` and the new `loop` syntax
16:15:51 <acozine> The two options are slightly different
16:16:00 <acozine> in the way they function, that is
16:16:23 <samccann> #topic loop vs with_*
16:16:50 <samccann> #info Ansible currently supports two different ways of looping over multiple items: the legacy `with_<filter_plugin>` and the new `loop` syntax. They function slightly differently
16:17:42 <acozine> the challenge for the documentation is to make sure we accurately describe the technical possibilities and limitations of each approach, and provide useful guidance for users on when to update playbooks and when not to
16:17:44 <samccann> #agreed loop vs with_* will be a main topic for next week's meeting. Please investigate beforehand so we can all discuss
16:18:07 <acozine> I can put a list of related PRs on the agenda as well
16:18:33 <samccann> #info docs needs to accurately describe technical possibilities/limitations of each and provide guidance for users on when to update playbooks and when not to
16:18:46 * gundalow -> afk
16:18:47 <samccann> ...not to turn everything you say into an info, but I'll forget in like 30 min...
16:18:57 <acozine> 47895, 47215, 47231
16:19:19 <acozine> oh, and 47244
16:19:32 <samccann> #info related PRs - 47895, 47215, 47231, 47244
16:20:07 <acozine> oops, it's `with_<lookup_plugin>`
16:20:13 <acozine> (not filter)
16:20:36 <acozine> clearly I need the docs (and my brain) updated!
16:20:42 <samccann> heh
16:22:44 <acozine> anybody else have a PR or issue to discuss, feedback on the docs, ideas for future work, etc., to bring up today?
16:24:10 * acozine suddenly feels she is speaking to empty air
16:24:47 <samccann> heh
16:25:35 <acozine> okay, looks like we all get five minutes back
16:25:59 <acozine> thanks folks! we made some progress today
16:26:27 <acozine> if anyone has feedback for the group or for me, please chime in on the channel or in a PM any time
16:26:36 <acozine> #endmeeting