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