16:01:17 <acozine> #startmeeting Docs Working Group aka DaWGs
16:01:17 <zodbot> Meeting started Tue Feb 23 16:01:17 2021 UTC.
16:01:17 <zodbot> This meeting is logged and archived in a public location.
16:01:17 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:01:17 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:17 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
16:01:23 <acozine> #topic opening chatter
16:01:26 <acozine> who's around?
16:01:41 * dericcrago waves
16:01:47 <acozine> #chair dericcrago
16:01:47 <zodbot> Current chairs: acozine dericcrago
16:01:50 <samccann> o/
16:01:58 <acozine> phew! I was gonna start singing "All By Myself" . . .
16:02:02 <acozine> #chair samccann
16:02:02 <zodbot> Current chairs: acozine dericcrago samccann
16:03:34 <acozine> abadger1999 andersson007_ bcoca dmsimard lmodemal alongchamps baptistemm briantist cyberpear felixfontein madonius mrproper tadeboro tributarian you folks talking docs today?
16:03:52 <briantist> sure
16:03:57 <tadeboro> o/
16:04:09 <acozine> #chair briantist tadeboro
16:04:09 <zodbot> Current chairs: acozine briantist dericcrago samccann tadeboro
16:04:15 <acozine> welcome, everybody
16:04:44 <acozine> just heard from lmodemal, her neighborhood lost power
16:05:28 <acozine> official agenda: https://github.com/ansible/community/issues/579#issuecomment-780056686
16:06:04 <acozine> #topic tidying from last week
16:06:13 <acozine> we had four action items last week
16:06:58 <acozine> of which, two and a half have been done
16:07:50 <acozine> the big docsite split PR is merged to `devel`
16:08:10 <acozine> (hooray!)
16:08:38 <acozine> though the fix was a little different than using `cp` instead of `ln`
16:08:46 <acozine> the 3.0.0 documentation is live
16:09:04 <samccann> woot!
16:09:16 <acozine> and samccann posted the minutes for 2 weeks ago
16:10:03 <acozine> the other two are still in progress: fixing the publication jobs so they do the right thing for changes to the `devel` branch, and finding out where the `/docs/` folder is on the AH roadmap
16:11:05 <acozine> unfortunately this means we have no updates on collections `/docs/` folder usage yet
16:11:30 <acozine> so I"m going to skip down the agenda a bit
16:11:47 <acozine> #topic documentation for filter and test plugins
16:12:08 <acozine> bcoca: are you around?
16:12:41 <bcoca> technically i exist in this plane at this time
16:13:13 <bcoca> ^ that is delayed till next version
16:13:17 <acozine> heh
16:13:18 <bcoca> we are in freeze now
16:13:21 <alongchamps> I'm around today
16:13:30 <acozine> do you have any updates on filter/test plugin docs?
16:13:41 <acozine> hi alongchamps!
16:13:44 <acozine> #chair alongchamps
16:13:44 <zodbot> Current chairs: acozine alongchamps briantist dericcrago samccann tadeboro
16:14:28 <acozine> bcoca: not sure if you're talking about a development freeze or the winter weather . . .
16:14:49 <bcoca> acozine: i thought one produced the other
16:15:03 <acozine> heh, could be
16:15:04 * bcoca queues snowpiercer episode
16:15:11 <lmodemal> o/
16:15:17 <acozine> anyway, any thoughts or progress on filter/test plugin docs?
16:15:22 <acozine> #chair lmodemal
16:15:22 <zodbot> Current chairs: acozine alongchamps briantist dericcrago lmodemal samccann tadeboro
16:15:24 * lmodemal lost power due to strong winds
16:15:34 <bcoca> [11:13] <bcoca> ^ that is delayed till next version
16:15:41 <bcoca> ^  that was my comment
16:15:57 <acozine> ohh, I missed the context
16:16:13 <samccann> so 2.12? (to be sure I'm following along here)?
16:16:38 <acozine> #info filter/test plugin documentation is delayed until ansible-core-2.12
16:17:37 <acozine> bcoca: is there anything we can do to help the process along? to have a PR reviewed, tested, and ready for merge as soon as 2.12 development opens up?
16:18:14 <bcoca> if you have clonning vats and/or spare tardis
16:18:39 <bcoca> most of the issue is adapting to the m'many ways' people not package the plugins and existing 3 docs formats
16:19:34 <acozine> thanks for the update bcoca
16:20:30 <acozine> #topic semantic markup proposal
16:20:57 <acozine> this is part of our ongoing discussion about formatting and markup for module documentation
16:21:08 <acozine> basis for discussion: https://github.com/ansible/ansible/pull/73137/files
16:21:51 <acozine> this is very much WIP; the PR gives us a place to record ideas, suggestions, objections, and so on
16:23:56 <acozine> if we adopt this proposal (or something like it), we would have to update every module's DOCUMENTATION section in the short term
16:24:52 <acozine> but once all modules used this approach, we could change the look of all the environment variables with a single chanage
16:24:57 <acozine> s/chanage/change
16:25:21 <acozine> have folks looked at the proposed PR?
16:26:11 <acozine> #chair
16:26:11 <zodbot> Current chairs: acozine alongchamps briantist dericcrago lmodemal samccann tadeboro
16:26:19 <tadeboro> I did and and I have nothing to add.
16:26:35 <felixfontein> (I'm around a bit now :) )
16:26:37 <acozine> tadeboro: do you think it would be worth the work?
16:26:43 <acozine> #chair felixfontein
16:26:43 <zodbot> Current chairs: acozine alongchamps briantist dericcrago felixfontein lmodemal samccann tadeboro
16:26:49 <tadeboro> And I know I will convert all of our modules to that markup as soon as it is ready to go.
16:27:35 <acozine> that's a vote of confidence, for sure
16:28:01 <dericcrago> what's the long term plan for the format macros?
16:28:05 <felixfontein> I agree with tadeboro; except the sentence "use standard Python formatting" which I don't really understand :)
16:28:23 <tadeboro> Because guessing what `I(bla)` means is something I would rather avoid. Is this something that author wanted to emphasize, is it a parameter, it is name of his cat, ...
16:28:32 <briantist> I like those proposed changes
16:30:19 <acozine> dericcrago: we've had discussions in the past about "params should be `code` instead of italics" but manually changing all the param references seemed troublesome, especially when the fashion in docs might change and next year they should be bold
16:30:21 <samccann> wasn't there some effort 'somewhere' to identify how many I() etc were in Ansible docs today (and thus a guess at how many we'd need to change etc)?
16:31:13 * samccann ponders next years semantic fashion - I heard Bold is the new Italics in 2021
16:31:17 <dericcrago> acozine, I guess where I was going with that is, do we want to mention or hint at format macros might go away in the future so don't rely on them?
16:31:25 <tadeboro> I think abadger<number> posted those numbers a while ago.
16:32:03 * tadeboro does not wake people up in the middle of the night
16:32:07 <felixfontein> dericcrago: why should some go away?
16:32:38 <acozine> dericcrago: also marking options with `I(option)` isn't intuitiive - why `I`? it will be easier to understand and remember `O is for option`
16:33:11 <tadeboro> O() is the main reason why I like the proposal.
16:33:17 <dericcrago> felixfontein - I'm not really suggesting whether or not they should or shoudln't, but if the plan is that they should (as in it's semantic only in the future) do we want to reference where we think we'll be in the future?
16:33:21 <bcoca> really 'action arguments' ... since we use 'args' as the alternate field .. but all docs state options
16:33:37 <acozine> the plain old format macros (I for italic, B for bold), will still exist, because Python provides those "for free"
16:34:10 <felixfontein> acozine: do you mean Sphinx or RST and not Python?
16:34:22 * acozine reads backscroll, plans to introduce all her cats' names to the docs immediately
16:34:29 <felixfontein> dericcrago: there are a lot of places where you want to format something that is not an option name, value, or env variable :)
16:34:34 <bcoca> acozine++
16:34:59 <acozine> felixfontein: oh, maybe so - I don't think those are ones we had to add just for Ansible, am I wrong about that?
16:35:26 <acozine> in which case the line about "standard Python formatting" is wrong
16:35:49 <felixfontein> acozine: I already added a comment for that ;)
16:35:55 <acozine> thanks
16:35:59 <bcoca> I see a fewmajor things 1) playbook objects 2) keywords 3)plugins (includes modules) 4) options/arguments to plugins 5) settings (ini/env/--cli/variable) 6) externals (libs, cli tools)
16:36:37 <acozine> bcoca: you mean you would like different formatting for those 6 things in the module documentation?
16:37:17 <acozine> this proposal only affects text in the `DOCUMENTATION` strings of modules/plugins
16:37:22 <bcoca> i see them as things that will need formatting/highliting and possible refs, do they all need to be diff .. no, but that can help users navigate them better
16:37:23 <felixfontein> acozine: I guess not different formatting, but different macros - the formatting can be identical in the end
16:38:08 <acozine> that makes sense
16:38:27 <samccann> there is likely a point at which there are  too many macros to remember
16:38:31 <bcoca> i was just enumerating them since i cannot find a good list in prev discussions
16:38:51 <samccann> P() playbook K() keywords etc etc.. if that's the leaning here?
16:38:55 <bcoca> samccann: ship sailed? i cannot remember more than 2 at time and need to look them up
16:39:15 <felixfontein> or the same macro, but with some information included that's not printed by default, like K(vars#keyword), K(task#playbook), ...
16:39:24 <samccann> bcoca - yeah -looking them up is fine, but seeing a list of 10 to decide between??
16:39:39 <bcoca> R(plugins/connection/sssh) ?
16:39:59 <briantist> I do like the semantic separation of all of those items, even if formatting ends up the same (for now), it really gives a lot of options (no pun intended) to change and style them in the future. I don't care if there are many, I end up looking at the documentation documentation nearly every time anyway
16:40:10 <felixfontein> bcoca: R() already exists, but it is hard to use for plugins since you need to know how their reference if build from the FQCN :)
16:40:28 <bcoca> samccann: well, theys hould be clearly documented or the other opion is samples felix and i just gave, have single 'generic' and allow details inside to make distinction
16:40:44 <acozine> briantist: me too, I open that page when I review a PR to module docs
16:40:44 <bcoca> felixfontein: random example, use X() instead
16:40:52 <felixfontein> I think we shouldn't introduce too many things at once right now though :)
16:40:59 <felixfontein> (to avoid making this proposal too complex)
16:41:15 <briantist> sure, not suggesting it all has to be done at once
16:41:29 <bcoca> felixfontein: i was giving short example, not complete schema, fqcn can be used as name in end but still need to konw 'is plugin' and 'plugin type'
16:41:40 <felixfontein> also the new things in the proposal are right now the most common that appear in module/plugin docs, so it's a very good start IMO
16:42:23 <felixfontein> references to plugins (similar to M() for modules) is the only thing that would be nice to add to the current proposal IMO, since that has been a pain point in the past that came up often enough I think
16:42:28 <acozine> I don't know how many module docstrings refer to playbook keywords . . . it might not be many; every module includes references to option names and values
16:42:39 <felixfontein> acozine: exactly :)
16:42:51 <acozine> bcoca: could you add your list of 6 items as a comment on the WIP PR?
16:43:01 <acozine> it's great feedback; we shouldn't lose it
16:43:13 <felixfontein> at least certain kind of plugins are referenced also quite often, like lookups (`use the file lookup to populate this module option`)
16:43:28 <felixfontein> (I'm AFK a bit now)
16:44:50 <bcoca> 90% of modules mentioning keywords are 'do not work with' or 'bad interaction'
16:44:58 <acozine> heh
16:45:01 <bcoca> but my 'attributes' proposal would even remove that
16:45:13 <acozine> that's probably information users need, then
16:45:17 <bcoca> since we would codify in the keywords - bypass_host_loop
16:45:33 <acozine> bcoca: link to that proposal?
16:46:20 <bcoca> https://github.com/ansible/proposals/issues/68
16:46:23 <acozine> thanks
16:47:54 <acozine> sounds like next steps include exploring the full range of items we want semantic markup for, adding the code to create the new macros, and creating issues for updating existing documentation
16:49:58 <acozine> I can't go over the hour-long meeting today, so I'm going to skip to open floor
16:50:05 <acozine> #topic open floor
16:50:25 <acozine> anybody have proposals, PRs, or issues that need attention?
16:50:40 <acozine> questions to ask the docs "hive mind"?
16:50:59 <acozine> all questions, comments, suggestions, and ideas welcome
16:52:01 <acozine> chat is welcome in  the channel any time, though depending on your time zone, it may take a few hours to get a response
16:52:08 <tadeboro> Do we know what will happen with content such as https://docs.ansible.com/ansible/latest/scenario_guides/guide_infoblox.html ?
16:52:35 <acozine> tadeboro: the current hope is that we can move those to collections in the next few months
16:52:39 <samccann> as in will it get updated or will it get moved to a collection /docs folder?
16:53:10 <tadeboro> That guide contains some serious errors, but I do not feel like spending a lot of time updating it if no one will take care of it later on.
16:53:42 * tadeboro has quite bad experience with Infoblox people
16:54:04 <acozine> is there an infoblox collection in Ansible 3?
16:55:01 <tadeboro> No, because the collection is in a bad shape.
16:55:05 <acozine> I hope we can move that guide to https://galaxy.ansible.com/infoblox/nios_modules
16:55:26 <acozine> even more reason to get the guide out of the official docs
16:55:33 <bcoca> https://github.com/ansible-community/ansible-build-data/blob/main/3/ansible-3.build <= easy way to answer all 'is it in a.3.0 questions'
16:55:43 <acozine> bcoca: thanks
16:56:21 <tadeboro> bcoca: But infoblox is a bit special, because part of the content is still part of community.network IIRC. So yeah, fun.
16:56:33 <acozine> heh
16:56:41 <acozine> so many special cases
16:56:54 <bcoca> our special cases have cases of special cases
16:57:09 <tadeboro> OK, so I guess I will wait with updates for now.
16:57:10 <acozine> thanks for the pointer, I can use that as an example when talking to the galaxy team
16:57:21 <acozine> tadeboro: sorry we don't have a more definitive answer
16:57:37 <acozine> I agree 100% that the guide should move
16:57:49 <tadeboro> I did not expect a clearcut answer. I know better by now ;)
16:58:04 <acozine> sigh
16:58:17 <acozine> other open floor items?
16:58:23 <felixfontein> maybe it would be great if (parts of) the galaxy team could come to a docs meeting where /docs/ is discussed
16:58:38 <acozine> yes
16:58:42 <felixfontein> tadeboro: it's community.general, not community.network :)
16:59:06 <felixfontein> because we had the /docs/ topic so often, and usually the discussion ends with that we need input from the galaxy/AH team
16:59:22 <acozine> now that the docsite split is (mostly) done, that can be our top priority on the "mechanical" side of things
16:59:42 <acozine> (I think of the docs work as half mechanical and half verbal)
16:59:53 <samccann> don't forget the hairpulling
16:59:54 <acozine> felixfontein: very true
16:59:56 <acozine> heh
16:59:57 <samccann> 1/4 hairpulling
17:00:06 <acozine> samccann: hairpulling exists on both sides
17:00:49 <acozine> all right, we'll try to have some progress on the collections docs by next week
17:01:09 <acozine> meanwhile I'm already late for my next meeting
17:01:10 <felixfontein> \o/
17:01:22 <bcoca> shaved head == solution for hairpulling
17:01:36 <acozine> thanks alongchamps bcoca briantist dericcrago felixfontein lmodemal samccann tadeboro
17:01:41 <acozine> #endmeeting