14:32:07 <samccann> #startmeeting DaWGs aka Docs Working Group 14:32:07 <zodbot> Meeting started Tue Oct 22 14:32:07 2019 UTC. 14:32:07 <zodbot> This meeting is logged and archived in a public location. 14:32:07 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:32:07 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:32:07 <zodbot> The meeting name has been set to 'dawgs_aka_docs_working_group' 14:32:11 <samccann> there we go! 14:32:19 <felixfontein> \o/ 14:32:19 <samccann> who's around to talk the docs? 14:32:25 <felixfontein> (I'm partially around) 14:32:29 <samccann> hey felixfontein !! 14:32:38 <samccann> #chair felixfontein 14:32:38 <zodbot> Current chairs: felixfontein samccann 14:32:48 <felixfontein> nobody else? 14:32:50 <samccann> ur furniture now! 14:33:09 <felixfontein> yay :) 14:33:28 <samccann> let's see who else might be around... bcoca gundalow cyberpear ? 14:34:10 * gundalow is off today 14:34:28 <samccann> #hammock gundalow 14:34:59 <samccann> ok well let's ease into it and see who trickles in. 14:35:16 <samccann> gonna skip bcoca proposal until he's available. Meanwhile 14:35:24 <samccann> #topic Galaxy docs update 14:35:59 <samccann> When last our intrepid group met, we talked about the galaxy docs coming over to docs.ansible.com. And a kind soul pointed out that they have separate release trains 14:36:15 <samccann> so I moved things around a bit and - http://docs.testing.ansible.com/ansible-galaxy/devel/index.html 14:37:09 <samccann> It will be its own section on docs.ansible.com (much like tower and ansible-lint are today). But the doc source is in ansible/ansible, under the docs/galaxy/docsite directory 14:37:14 <samccann> (or will be I should say) 14:37:34 <felixfontein> is galaxy already in the ansible/ansible repo? 14:37:40 <samccann> intersphinx crossref will work 14:38:02 <samccann> galaxy itself, no. Galaxy documentation will be. it's currently a PR 14:38:37 <samccann> #link https://github.com/ansible/ansible/pull/63695 14:39:38 <samccann> my current snag - we have a site search on ansible/ansible docs. I need to get that to work for the galaxy docs as well (right now it's still searching ansible/ansible docs so to speak) 14:40:14 <felixfontein> hmm, why not have the galaxy docs in the galaxy repo? if they're in the ansible docs, it will be a lot harder to version them correctly 14:40:33 <samccann> the galaxy docs are currently in the galaxy repo 14:40:58 <samccann> but there is only one 'version' so to speak. since there is only one version of galaxy UI available 14:41:21 <felixfontein> then why not keep the galaxy docs in the galaxy repo? is there any advantage for them being in the ansible repo? 14:41:26 <samccann> So the thought was we could bring them into ansible/ansible so that it can benefit from all our setup/process etc 14:42:02 <samccann> right now - we (ansible docs) can't control the publishing at all. 14:42:05 <felixfontein> if galaxy and ansible would have the same release schedule, that would be a good idea, but with different schedules I think it makes it more complicated in the end 14:42:13 <acozine> I'm in the last twenty minutes of a meeting, but hope to become furniture soon! 14:42:15 <samccann> possible, yes 14:42:36 <felixfontein> it might be better to move the docs tools out of the ansible/ansible repo, and use the from both galaxy and the ansible repos 14:42:38 <samccann> which is why I try to talk about it here so folks like you can lend a hand on the Deep Thoughts of how this should work 14:42:58 <samccann> Originally, I was thinking they would just be part of ansible docs. but yeah, was forgetting the separate versions. 14:43:09 <felixfontein> which docs tools will be used by both repos? 14:43:39 <samccann> thinkin 'out loud' now - I don't know if there is an easy way to have the doc source repo over on galaxy, but published as a separate product on docs.ansible.com 14:43:41 <felixfontein> I guess the theme and plugins (for formatting) are on the list 14:44:08 <samccann> the plugins? as in ansible plugis or just all the theme stuff that makes ansible docs work? 14:44:17 <felixfontein> no, the sphinx plugins 14:44:37 <felixfontein> I think there's only one, namely for extending pygments 14:44:43 <samccann> yeah so I want to reuse the same sphinx work. Otherwise I'm maintaining it in two places 14:44:52 <samccann> so ideal goals, to bring this to the beginning: 14:45:00 <felixfontein> https://github.com/ansible/ansible/tree/devel/docs/docsite/_extensions 14:45:02 <felixfontein> there it is 14:45:04 <samccann> 1 - use same sphinx theme etc files 14:45:32 <samccann> 2 - allow the docs team to publish updates/fixes w/o having to drag the galaxy developers in to do it for us 14:45:53 <samccann> 3 - allow our intrepid community to help maintain/update with PRs much as y'all do today with all the other ansible docs 14:46:31 <samccann> 4 - releive the galaxy developers from maintaining all the galaxy docs on their own (mostly what they've been doing today) 14:46:47 <felixfontein> I don't know how the galaxy repo "works". can one do PRs for the docs there, and do you have commit rights to merge them / backport them? 14:46:56 <samccann> so those are the driving factors in all this. moving from galaxy git repo to ansible repo was the way I could think of to do it 14:47:44 <felixfontein> for the common files/tools (like sphinx theme, extensions, ...): one could put them into a separate repository (github.com/ansible/docs-tools), and "vendor" them into both the galaxy docs and ansible docs. that's a bit more work if you change them, but since they're mostly not changed, I guess that should be ok 14:47:55 <felixfontein> assuming you can work with the galaxy repo the same way as with the ansible repo 14:47:58 <samccann> acozine and I don't have rights to galaxy repo no. We probably could get that part. What I don't know off the top of my head - today galaxy docs are IN galaxy. I don't know if we (acozine and I) can publish those galaxy docs as needed w/o affecting the galaxy creation itself 14:48:36 <felixfontein> that's a good question. maybe we need someone from the galaxy team to tell us more how it works? 14:49:15 <samccann> yep, I can go back and ask these questions for sure. I was on a one-woman mission to move it all over to where I understood how things worked. Might not have been the right track :-) 14:50:49 <samccann> What I'm wondering is - if we leave everything in the galaxy git repo, can we still publish to docs.ansible.com/ansible-galaxy or something like that? I'm guessing we can, because Tower does something like this. 14:51:21 <acozine> hallo - other meeting is done, my attention is all here now 14:51:33 <felixfontein> I don't know how the publishing step works, but I guess it can be arranged :) 14:51:36 <samccann> #info - consider putting common files/tools (sphinx, theme, extensions) in separate repo and then 'vendor' them to both ansible/ansible and galaxy for docs 14:51:41 * acozine awaits her furniture fate while looking back over the conversation so far 14:51:47 <samccann> #chair acozine 14:51:47 <zodbot> Current chairs: acozine felixfontein samccann 14:54:07 <samccann> so if we try this approach felixfontein - as a docs contributor, do you think you'd edit/fix galaxy docs as you do today for ansible/ansible docs? Because an important goal here is that our docs community helps keep galaxy docs updated so to speak 14:54:33 <samccann> (assuming of course that you'd be using galaxy more in the future now that collections are rolling out) 14:55:30 <acozine> so here's my summary, tell me if I've got this right . . . . 14:55:47 <felixfontein> assuming I'll use galaxy more, I guess I'd also fix docs issues when I find them 14:56:46 <acozine> leave the Galaxy docs in the ansible/galaxy repo, move the common parts of the docs pipeline (sphinx extensions, CSS, etc.) into a separate repo that can be equally accessed by ansible/ansible, ansible/galaxy, and any other repos we want to add to that list 14:57:05 <acozine> is this ^^^ the proposal on the table? 14:57:22 <samccann> and publish galaxy on docs.ansible.com yes 14:57:35 <samccann> so it's no longer tied to galaxy. 14:57:45 <acozine> right 14:57:51 <samccann> (or the galaxy UI I should say) 14:57:58 <acozine> if we can make this approach work, I think it would be a great one 14:58:25 <felixfontein> if you vendor that separate repo into the other repos, you can change the theme in one version without affecting the others (with all disadvantages and advantages :) ) 14:58:36 <acozine> it would mean over time we can bring other projects like ansible-lint into "the fold" and consolidate the styling 14:58:43 <felixfontein> if you don't vendor it, building the docs gets more complicated though 14:59:13 <acozine> I'm not familiar with the use of the word "vendor" as a verb 14:59:23 <samccann> hmm. not sure we want to change one theme? The goal is to not maintain multiple themes... just the one 15:00:34 <acozine> so I'm not sure what's involved in "vendoring" the docs stuff - felixfontein do you know of a good example I can learn from? 15:02:35 <samccann> i found this - https://medium.com/opsops/git-vendor-295db4bcec3a 15:02:47 <samccann> #link https://medium.com/opsops/git-vendor-295db4bcec3a possible info on git vendoring 15:03:29 <samccann> are we agreed to try this approach (keeping galaxy docs in galaxy but using git vendor to share the theme and extensions across both?) 15:03:31 <zbr> submodules could work 15:03:53 <samccann> thanks zbr and welcome to the docs meeting! 15:03:59 <samccann> #chair zbr 15:03:59 <zodbot> Current chairs: acozine felixfontein samccann zbr 15:04:12 <felixfontein> zbr: indeed, but I'm not sure whether adding submodules to ansible/ansible would be ok 15:04:34 <acozine> samccann: I think it's a good approach - it means the galaxy devs can submit docs to go with code changes, which gives us at least a starting point for documenting new features 15:04:34 <felixfontein> especially since it only affects docs, and nothing else 15:04:36 <zbr> felixfontein: depends how many you plan to add. 15:04:55 <acozine> welcome zbr! 15:05:28 <acozine> also, thanks for the post on vendoring, I shall read and learn 15:05:36 <acozine> samccann: ^^^ 15:05:37 <felixfontein> zbr: since this would be the very first submodule, there might be a lot of resistance 15:06:25 <felixfontein> anyway, vendoring seems to be very common in the Go community (the programming language go, not the game) 15:06:31 <samccann> #agreed keep galaxy docs in galaxy repo. move theme and associated files/tools/extensions to a n ansible/docs-tools repo and use git vendor/ or similar approach to share across both docsites. publish galaxy docs as product on docs.ansible.com 15:07:36 <felixfontein> note: "git vendor" is a specific implementation, vendoring is a general process (which can be defined to even include submodules I think) 15:07:58 <samccann> #info git vendor" is a specific implementation, vendoring is a general process (which can be defined to even include submodules I think) 15:08:12 <samccann> thanks everyone! 15:08:48 <samccann> going to move to the next topic... 15:09:04 <samccann> #topic https://github.com/ansible/proposals/issues/68 15:09:16 <felixfontein> btw, a language question: what does the 'verb' "to shoe horn" mean? (https://github.com/ansible/proposals/issues/68#issuecomment-368475098) 15:09:26 <samccann> don't think we have bcoca today, but please take a look 15:09:46 <acozine> felixfontein: to "shoe-horn" is to stuff something into a tight space, physically or metaphorically 15:10:11 <felixfontein> ok 15:10:21 <acozine> a shoe horn is the metal guide you put at the back of your shoe to help your foot slide in, especially if the shoe is tight 15:10:25 <felixfontein> in that case I don't see why it is shoe horned incorrectly :) 15:10:41 <felixfontein> ah 15:11:37 <samccann> i think that was just a philosophical debate on dropping the use of idempotent in ansible. not directly related to the proposal itself 15:12:35 <acozine> agreed, the person is saying we shouldn't use the word "idempotent", mainly because it isn't simple, plain English 15:12:46 <felixfontein> that's true, maybe we should move that discussion somewhere else :) anyway, I'm for keeping idempotence / idempotent. but then, I'm a mathematician and familiar with that word ;) 15:12:59 <acozine> bcoca: are you here? 15:13:49 <acozine> felixfontein: so, how is "idempotent" correctly pronounced, do you know? 15:14:14 <acozine> is it eye-DEM-poh-tent? EYE-dem-POH-tent? 15:14:56 <acozine> and does the emphasis change for "idempotence" or "idempotency"? 15:16:09 <felixfontein> I was never really good with emphasis in english, so I'm not that sure (I could tell you in german though :) ). I would guess EYE-dem-POH-tent though. 15:16:31 <acozine> darn, I was hoping to figure that one out ;-) 15:16:35 <felixfontein> hehe :) 15:16:42 <samccann> personally I use the latter as well 15:16:48 <felixfontein> I'm more concerned that alternatives are either long formulations, or too imprecise 15:16:51 <acozine> I avoid the word because I don't like sounding both pretentious AND ignorant at the same time 15:17:11 <samccann> lol. 15:17:13 <acozine> and mispronouncing it sounds like both 15:17:31 <samccann> meanwhile, back at the proposal...any comments on that aspect? 15:17:38 <acozine> avoid it in spoken language, that is 15:17:46 <acozine> ah, right, the proposal 15:17:47 <felixfontein> hehe, that's true :) I as a non-native english speaker have the advantage that I'm mispronouncing some stuff wrongly anyway, so it's probably ok ;) 15:18:12 <felixfontein> I like the idea of the proposal 15:18:21 <felixfontein> haven't looked in the details yet 15:18:27 <felixfontein> I'll have to run for the train now, so bbl 15:18:31 <bcoca> as an american, i consider myself a non native english speaker 15:18:34 <acozine> I like the concept, though I'm not sure how big of a problem it is 15:18:38 <acozine> bcoca: heh 15:18:54 <samccann> thanks felixfontein! 15:18:54 <bcoca> im in 3 meeitngs, just ralized i was pinged here 15:18:56 <acozine> bcoca: can you link to examples of the repeat text 15:19:01 <bcoca> repeat? 15:19:17 <acozine> the proposal says "This is a LOT of repeat text" 15:19:40 <acozine> I'm wondering what you meant/where the repetitions happen 15:19:43 * bcoca checks context 15:19:57 <bcoca> ah, the 'documentaiton' on what each property is 15:20:14 <bcoca> much like supported_by we use keyword in modules but not the full description, which docs take care of 15:20:53 <acozine> example? 15:21:03 <bcoca> supported_by: community? 15:21:16 <bcoca> ^ we just use keyword, not the fulld escription 15:21:24 <samccann> so would the approach be - create the document snippets for each new keyword, code up support for the keyword... then tiptoe through all the modules that have this duplication and replace it w/ the new keyword? 15:21:39 <bcoca> samccann: except no modules document this 15:21:53 <bcoca> some document one that i didnt add 'plaform: windows' 15:22:02 <acozine> I thought some modules documented "supports check mode" 15:22:02 <samccann> ah so tiptoe through the modules that need this and add the keyword 15:22:17 <bcoca> acozine: i have not seen one, but 3k modules ... 15:22:19 <samccann> (aka there's some undocumented stuffs in there today) 15:23:26 <acozine> are all the fields boolean? 15:23:49 <acozine> the fields to be included in the proposed `properties` section? 15:24:21 <acozine> I grepped for "check mode" in the module docs : 15:24:24 <bcoca> unsure, i was thinkig of platrom: posix|windows|aix, etc 15:24:31 <bcoca> ios ... 15:24:39 <bcoca> to signify supported target platforms 15:24:43 <acozine> https://www.irccloud.com/pastebin/9CbKMq6R/module%20docs%20that%20mention%20%22check%20mode%22 15:25:38 <acozine> support for posix/windows/aix/??? isn't something we can test for, is it? 15:26:02 <bcoca> sometimes, but it is mostly for the module author to indicate for user 15:26:19 <bcoca> ^ i get blank page on your link 15:26:42 <samccann> one thing I want us to keep in mind with improving module docs - we have a 2nd pipeline in the works as we speak - for modules within collections coming from galaxy 15:27:12 <samccann> at some point, they both need to have the same result for the end reader so to speak. 15:28:35 <samccann> as I understand it - module docs will be displayed within galaxy itself, and also brought back into docs.ansible.com. I don't know how long this dual module docs pipeline will be in place, but it's something to keep in mind as we change one, we need to change the other 15:29:18 <acozine> currently module docs will not display in the Galaxy UI, but soon, we hope, they will 15:29:43 <acozine> bcoca: 97 modules mention "check mode" 15:30:52 <samccann> we're getting to the end of the meeting time... 15:31:15 <bcoca> acozine: gtk, but i would not make it a rule to eliminate them, jsut the proposal makes it redundant 15:31:43 <acozine> bcoca: I think your proposal is an interesting to one, can we pick one or two modules as examples and then work through questions based on those? 15:32:12 <bcoca> i suggest debug, template and apt 15:32:14 <acozine> it's easier to have a conversation about this kind of thing with a concrete example 15:32:18 <acozine> excellent! 15:32:36 <bcoca> those cover most cases 15:32:37 <samccann> ok just in case anyone was lingering to the end for... 15:32:43 <samccann> #topic Open Floor 15:32:46 <bcoca> hmm, add_host .. for a bypass host loop 15:32:52 <samccann> will linger a few minutes just in case 15:33:05 <acozine> what's our open PR count today? 15:33:11 <samccann> anyone have anything not on the agenda to bring up while a few of us are around? 15:33:40 <acozine> today's open docs PR count: 104 15:33:43 * acozine sighs 15:33:51 <samccann> and 232 issues 15:34:05 <acozine> and a release coming up 15:34:26 <samccann> yep. speaking of which, we have som `P3` issues 15:34:37 <samccann> https://github.com/ansible/ansible/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Adocs+label%3AP3 15:34:39 <acozine> yikes 15:35:17 <acozine> well, let's close the official meeting . . . because those may take some time 15:35:17 <samccann> just noticed today. They don't block anything, but they do have a higher priority than the other 230-ish issues if anyone wants to pick up something important 15:35:28 <samccann> #endmeeting