16:00:19 <acozine> #startmeeting Docs Working Group aka DaWGs
16:00:19 <zodbot> Meeting started Tue Jan  5 16:00:19 2021 UTC.
16:00:19 <zodbot> This meeting is logged and archived in a public location.
16:00:19 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:19 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:19 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
16:00:23 <dericcrago> time for Docs Talk!
16:00:23 <felixfontein> happy new year!
16:00:28 <acozine> #topic opening chatter
16:00:35 <acozine> Happy New Year everybody!
16:00:40 <lmodemal> DING DING DING!  DaWGs (documentation working group meeting) happening now https://github.com/ansible/community/issues/521
16:00:47 <samccann> happy new year!
16:00:54 <acozine> #chair lmodemal dmsimard abadger1999 dericcrago samccann felixfontein
16:00:54 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein lmodemal samccann
16:01:27 * gundalow waves
16:01:28 <acozine> who else is around?
16:01:28 <abadger1999> Never has a new year felt so needes
16:01:40 <acozine> abadger1999: yes, it was time, and then some!
16:01:43 <acozine> #chair gundalow
16:01:43 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein gundalow lmodemal samccann
16:01:47 <tadeboro> o/
16:01:54 <acozine> #chair tadeboro
16:01:54 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro
16:02:07 <abadger1999> Hi tadeboro!  Glad you're back :-)
16:03:01 <acozine> New year, new agenda issue: https://github.com/ansible/community/issues/579
16:04:52 <acozine> and to anyone who is watching this chat, and wondering "how do I join this group?" or "why are some people `chairs`?" . . .
16:05:13 <acozine> anyone can bring up any docs-related topic at any time
16:05:29 <acozine> questions, comments, suggestions, and more are welcome, always
16:05:48 <acozine> we have official meetings once a week on Tuesdays (right now!)
16:05:53 <acozine> and anyone can join those too
16:06:08 <acozine> if you want to be a chair, just wave
16:06:10 <acozine> like this:
16:06:15 <acozine> o/
16:06:52 <acozine> and anyone can add an agenda item to the issue linked ^^^
16:07:31 <acozine> being a chair means you get a notification if we take a vote in the meeting
16:08:06 <samccann> and who doesn't want to be furniture... amirite?
16:08:12 <acozine> +1
16:08:45 <gundalow> :D
16:09:11 <bcoca> how do i escape?
16:09:18 <gundalow> bcoca: stand up
16:09:27 <acozine> #topic long-running issues from https://github.com/ansible/community/issues/579#issuecomment-750470261
16:09:31 <acozine> #chair bcoca
16:09:31 <zodbot> Current chairs: abadger1999 acozine bcoca dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro
16:09:36 <bcoca> gundalow: i work in standing desk ...
16:10:17 <acozine> bcoca: if you'd just kept your fingers away from the keyboard, you'd have escaped .  . . but you typed something and now you're furniture
16:10:28 <bcoca> acozine: drats!
16:10:40 <acozine> it's all about choices, bcoca!
16:11:14 <acozine> we have a lot of ongoing topics/work/decisions carried over from last year
16:11:47 <acozine> I feel like they've been on the agenda for a long, long time
16:12:15 <samccann> that they have
16:12:18 <acozine> I wonder if we can find ways to make progress on some of them, or set them aside for a few months, or something
16:12:26 <acozine> here's the list:
16:12:27 <abadger1999> <nod>
16:13:24 <acozine> https://www.irccloud.com/pastebin/hNYJt512/list%20of%20long-running%20topics
16:14:09 <samccann> was there a decision on option:value?
16:14:32 <acozine> abadger1999: how are you feeling about the release process now? Would getting to a bitflip release make a big difference?
16:14:51 <acozine> samccann: oh, did I forget something?
16:14:55 <acozine> if so, that would be awesome
16:15:12 <acozine> (the decision, I mean, not me forgetting stuff)
16:15:19 <samccann> heh well I remember we  talked a lot about it.  I'd have thought we settled on something?\
16:15:37 <abadger1999> I think it's a good thing to do but the work is largely for relrod and me.... if we want to take it off the docs agenda until the two of us have some actual change in process, that could work provided you all think it will be an improvement too.
16:16:09 <abadger1999> s/change in porocess/change to the process/
16:16:46 <acozine> abadger1999: sounds good, I think it would be nice to have a clean, simple, straightforward, automated release process that publishes the most recent docs, but I don't feel burdened by the current state of things
16:17:00 <abadger1999> Cool.
16:17:35 <acozine> #agreed remove bitflip release process from the active agenda for now
16:18:01 <samccann> ok last meeting minute I can find on the module formatting is  - ACTION: abadger1999 to figure out how many formatted entries we have
16:18:01 <samccann> in the ansible docs build
16:18:11 <samccann> tho the context is lost to me
16:18:24 <abadger1999> Hmm.. I forgot that.  Let me look at the logs and assemble those stats
16:19:01 <samccann> from the logs -  I could probably give statistics on how many `I()`, `C()` and `B()` entries there are i nthe ansible docs build
16:19:17 <samccann> https://meetbot.fedoraproject.org/ansible-docs/2020-12-15/dawgs_aka_docs_working_group.2020-12-15-16.01.log.html if you want to see it
16:19:23 <acozine> I kinda remember that - the debate was over "how many lines would that PR have if it made all the `option: value` entries the same?
16:20:25 <samccann> And do we go to full semantic markup. So the first step was how many of these would we need to change
16:20:51 <acozine> ah, yes, i do remember that discussion
16:21:11 <samccann> #info last we talked about module formatting, we decided to check how many C(), I() etc is already in the docs. Then create a proposal for full semantic markup based on how hard it would be to change everything
16:21:20 <samccann> that's what I got out of the meeting log
16:21:50 <gundalow> Could someone please remind me what was driving this change?
16:22:40 <samccann> someone didn't like the look of what we have today (which I think is italics?)  So we opened up the can o worms of a - how do we want it to look, and b - does this mean we should take the opportunity  to switch to full semantic markup
16:22:48 <gundalow> Just trying to understand cost vs benefit
16:23:07 <acozine> gundalow: it started with a PR that changed an entry from `code` to 'italics'
16:23:17 <samccann> if we do semantic markup, then we'd never have to change the source again
16:23:33 <samccann> we could go from italic to bold to monospace as the whims hit us
16:23:40 <acozine> yep
16:23:53 <acozine> right now we have some (maybe lots of) inconsistencies
16:23:59 <samccann> but yeah, a lot of work to do that.  So it's that vs 'just make them C() and move on'
16:24:28 <felixfontein> 'just make them C()' is also a lot of work
16:24:34 <samccann> and the final bit - educating contributors to the correct markup, whatever we decide
16:24:44 <acozine> anything we do to make it consistent is a lot of work
16:24:53 <acozine> and then there's maintenance
16:25:12 <samccann> <nods>  yep, which was why we left it at - find out how many of each we have today and if we could programatically make the switch for most of them to ease the transition
16:25:48 <felixfontein> existing ones could be wrong (they are in some cases), so automatic translation won't work that well
16:26:19 <samccann> yep, so 4K pages, across 70+ repos and growing
16:27:12 <samccann> though to balance that - what would it all be in say 3 years?  10k pages?  dunno
16:27:50 <samccann> and whatever we change, we'd need to pass that on to galaxy-ng folks as it would potentially impact their rendering too
16:28:23 <acozine> yep, and entropy will make things worse no matter what - if we get some consistency going now, and document the correct way to handle this stuff, things will be better when we hit 10K pages
16:28:23 <samccann> bcoca: would it impact ansible-docs as well?  I forget
16:28:26 <gundalow> <devil's advocate> Do we care (enough to fix it all)
16:28:44 <acozine> gundalow: some days we do . . .?
16:29:03 <gundalow> hehe
16:29:10 <abadger1999> samccann: it would.
16:29:17 <samccann> given all we have going in docsland? I'd put it as low on the priority list. But as acozine says - it's a growing problem IF we ever decide to change it
16:29:35 <acozine> interestingly, it's not a common complaint from users (at least not one that i hear), but developers occasionally complain about it
16:29:41 <abadger1999> ansible-docs doesn't share the rendering code with us.  (I've been talking with the galaxy folks off and on so there's at least the chance that the galaxy docs could share the renderer)
16:29:45 <gundalow> don't get me wrong, I've personally done hugs PRs where I've fixed this type of thing before. Though that's only been when I've had CI in place to ensure it doesn't get worse
16:29:54 <gundalow> or revert to previous bad state
16:30:18 <bcoca> @samccann sorry, other meeting, what specificly would impact ansible-docs?
16:30:21 <samccann> is CI possible for this? if we decide on some fixed end state?
16:30:49 <samccann> bcoca - toshio answered... if we change the mark up on modules, would ansible-doc code have to change as well
16:30:55 <felixfontein> CI is hard, since there will be false positives
16:30:57 <bcoca> yes
16:31:00 <samccann> thanks
16:31:12 <bcoca> but minor, ansible-doc morstly just removes markup
16:31:27 <felixfontein> adjusting ansible-doc should be simple
16:31:32 <samccann> so if we can't necessarily CI, then we'd not be able to force future modules to comply
16:31:52 <bcoca> _CONST = re.compile(r"\bC\(([^)]+)\)")
16:32:03 <bcoca> ^ set of expressions we use to remove markup,
16:32:15 <felixfontein> samccann: with proper names for the markup (I and C are not really helpful), it will probably be less a problem in the future for new content
16:32:24 <samccann> #info ansible-docs code removes markup so not a big impact if we go to semantic or other markup changes
16:33:00 <samccann> #info CI may not be possible to enforce markup down the road, but might be if we choose good markup names?
16:33:01 <bcoca> well, depends,  how easy it is to isolate the new markup from actual 'valid expressions'
16:33:09 <gundalow> samccann: I was wondering that as well. Could detect `O(key=value)` something like `C\(\w+ ?= ?\w+\)` and error if group1 (key) is found to be an option in the module doc
16:33:18 <felixfontein> there are also modules which simply use RST formatting (saw that yesterday I think: https://github.com/containers/ansible-podman-collections/blob/master/plugins/modules/podman_container.py#L77)
16:33:39 <gundalow> erm `(C|I)\((\w+) ?= ?\w+\)`
16:33:50 <felixfontein> gundalow: suboptions make that more complicated. or if someone is talking about an option of a different module/plugin.
16:34:11 <gundalow> felixfontein: urgh, that's a very valid and horrible point
16:34:20 <felixfontein> "Instead, use the O(baz) option of M(foo.bar.other_module)"
16:34:20 <gundalow> Thank you :P
16:34:29 <bcoca> suboptions == 'fun' ... also, comming soon to plugins, not just modules
16:34:51 <samccann> so does that suggest even with good names, we can't CI all this well?  should I undo the last minute?
16:35:04 <gundalow> acozine: samccann like you said earlier, feels like there maybe higher priority things to do
16:35:35 <samccann> maybe we put it as an issue and leave it in the docs issue list to 'marinate'?
16:35:54 <acozine> I am tempted to say "not in 2021, at least not until we get bored"
16:36:05 <samccann> yeah thus the marinating issue
16:36:11 <acozine> yeah, I like that
16:36:34 <felixfontein> I guess the whole process goes in two steps anyway: 1) decide names of new markup, make sure it is implemented on all sides and documented, 2) when that's done, start using it in module and plugin docs
16:36:44 <felixfontein> 1) is rather easy to implement; the hard work is 2)
16:36:45 <acozine> though an issue would be stronger if it included some indication of how we want it to be
16:36:52 <felixfontein> but 2) is not really urgent
16:36:56 <acozine> felixfontein: yep
16:36:59 <samccann> and 3) maintain it over time when people aren't using it correctly
16:37:09 <samccann> #3 is the ongoing one  that worries me most really
16:37:25 <felixfontein> 3) will be a lot easier than maintaining the current state
16:37:31 <acozine> yeah
16:37:36 <felixfontein> since I() and C() are far from obvious :)
16:37:57 <samccann> ok so either we punt this for 2021, or we decide which way to go (#1) and then punt it for 2021... which do we want?
16:38:21 <bcoca> do we have full docs of current markup:?
16:38:21 <acozine> yeah, and right now when we try to maintain our documented rules, we get right back into this discussion
16:38:28 <acozine> bcoca: yeah
16:38:29 <abadger1999> yes
16:38:48 <bcoca> k, i remember having some of it , didnt know if we ever completed the list
16:38:56 <felixfontein> samccann: it's already 2021
16:39:03 <abadger1999> So if we do nothing... does that mean we should take PRs and encourage people to take PRs for fixes to obey the current convention?
16:39:06 <samccann> heh
16:39:07 <acozine> https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#linking-and-other-format-macros-within-module-documentation
16:39:14 <bcoca> felixfontein: we restarted year count
16:39:33 <abadger1999> We're just not going to add new features yet?
16:40:08 <bcoca> nice
16:40:17 <acozine> abadger1999: yeah, that does worry me a bit
16:40:52 <acozine> I guess I'd vote for samccann's "figure out how it should be, change the documentation, create an issue, and let it marinate"
16:41:02 <samccann> for me, it's back to - limited time, lots to do, what's the best 'bang' for the buck
16:41:28 * bcoca goes back to getting filter/test docs
16:41:42 <samccann> ok we can't change the documentation w/o changing antsibull as well to handle whatever new thing we come up with
16:41:47 <felixfontein> bcoca: btw, any visible stuff for that? a branch, pr, ...?
16:42:22 <acozine> samccann: so, if we get a PR that changes `C(option: value)` to `I(option: value)` (which is what our current docs say is correct), we merge it?
16:42:46 <felixfontein> acozine: ATM yes, until we standardized the new way and began implementing it
16:42:56 <felixfontein> I can help with implementation - it should really not be much work
16:43:27 <samccann> well we can a) leave it as documented and accept whatever prs match, b) document a new way and get that approved and then change antsibull to render
16:43:40 <felixfontein> who needs to approve it?
16:43:43 <samccann> or c) do it all, which I think we decided against for now
16:43:49 <samccann> community at least
16:44:12 <samccann> if we are going to say 'don't use I(), C() use instead these three new other semantic markups and we'll decide how it renders'
16:44:39 <samccann> module authors will have say 3 new markups to use vs the ones they know today
16:45:01 <samccann> so imo we at least have to have a proposal/discussion in github to agree
16:45:03 <acozine> we could also say "just us C() for everything"
16:45:13 <samccann> which is not semantic
16:45:15 <acozine> nope
16:45:48 <samccann> so yeah, we have to also decide - do we do the quick/easy 'use c() for everything' or semantic markup.  The last meeting I remember there was strong feeling to go semantic
16:45:59 <acozine> yeah, there was
16:46:05 <samccann> but that could be all the christmas chocolates talking
16:46:21 <tadeboro> Wearing my ansibe-collection-maintainer, I do not care much about the exact direction things go. But being to able to write things in a way that will not be deprecated in a few months is important.
16:46:31 <acozine> and if our goals are maximum flexibility and precision, then semantic is the right way forward
16:46:39 <samccann> so let's start with a quick vote on semantic markup maybe?
16:46:51 <samccann> #topic do we or don't we adopt semantic markup
16:46:51 <tadeboro> My inner mathematician would like to see semantic markup ;)
16:47:19 <samccann> the pros are - we can change how things look anytime we want. The cons are - users have to learn something new
16:47:20 <felixfontein> mine too
16:47:37 <samccann> sorry module developers have to learn something new
16:47:37 <felixfontein> +1 for semantic markup
16:47:38 <acozine> yeah, agreed, it would feel very tidy
16:47:56 <samccann> any more discussion, or should we vote?
16:47:56 <acozine> is there any way we can test for it?
16:48:05 <samccann> test for what?
16:48:09 <abadger1999> +0.5.  I think I have similar  feelings to tadeboro but I don't think it's important for me personally whether to change to semantic or not.
16:48:18 <felixfontein> since I() and C() can still be used (for other things), there's not much we can test for
16:48:45 <acozine> we're talking about using something like `O(option)` and `V(value)`, right?
16:48:54 <felixfontein> at least now it will be clear that I() and C() are italics and code-style, and not options and values :)
16:48:55 <acozine> that's what we mean when we say semantic markup?
16:49:01 <abadger1999> unless we deprecate I() and C() with the goal of removing them entirely sometime.
16:49:03 <felixfontein> acozine: yes, and O(option=value) or O(option: value)
16:49:10 <samccann> something like that yes the markup says what the object IS  not how it would render
16:49:23 <felixfontein> abadger1999: I wouldn't do that, since there's both need for italics and code-style that's not an option value
16:49:50 * abadger1999 looks in the crystal ball and sees ansible-2090 has a full range of docbook attributes embedded ;-)
16:50:49 <acozine> all right, how about I do a WIP PR that would change the "documenting your module" page
16:51:02 <acozine> that would illustrate the changes we have in mind
16:51:09 <acozine> then we ask for feedback there
16:51:09 * samccann joins abadger1999 and sez it's asciidoc
16:51:10 <gundalow> abadger1999: 2 days into the working year and you are already suggesting XML. That's a red mark against your name
16:51:29 <acozine> of course there would need to be work done on the pipeline too
16:51:37 <acozine> but at least everyone could see what we're proposing
16:51:58 <acozine> and abadger1999 can get those stats so we know how many changes would be needed
16:52:11 <acozine> does that sound like a way forward?
16:52:13 <samccann> +1
16:52:32 <lmodemal> +1
16:52:34 <acozine> the core team and galaxy folks and whoever else can chime in that way
16:52:55 <acozine> #chair
16:52:55 <zodbot> Current chairs: abadger1999 acozine bcoca dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro
16:53:11 <abadger1999> @gundalow not suggesting... warning ;-)
16:53:29 <gundalow> abadger1999: ah, OK
16:53:36 <tadeboro> +1 (id we are voting on preparing a WIP PR)
16:53:43 <acozine> heh
16:53:55 <acozine> yep
16:54:12 <acozine> we've got 5 minutes left in today's meeting
16:54:39 <acozine> #action acozine to create a WIP PR that illustrates proposed semantic markup, solicit feedback
16:54:41 <samccann> #agreed - create a WIP PR that changes the documentation to what we are proposing (semantic) and use that for review/feedback
16:54:43 <acozine> heh
16:54:44 <felixfontein> so what exatly are we voting on right now?
16:54:47 <felixfontein> ah
16:54:48 <felixfontein> +1
16:54:51 <acozine> heh
16:55:09 * tadeboro is happy he is not the only one confused ;)
16:55:09 <gundalow> +1 (assuming it can be timeboxed)
16:55:17 <acozine> okay, quick update that didn't make it onto the official agenda
16:55:23 <samccann> acozine can you post the list of open items again to see if there's anything else we can knock off the plate?
16:55:30 <bcoca> afaict 'create proposal, get feedback'?
16:55:32 <bcoca> +1
16:55:48 <acozine> https://www.irccloud.com/pastebin/zyXyNCqJ/
16:56:22 <samccann> tadeboro and others - yes, the vote was 'create a WIP PR of what we are proposing and use that for feedback/approval'
16:56:23 <acozine> I'm just looking for "How do we drive this toward a decision so we can stop talking about it, do something, and move on?"
16:56:32 <acozine> We've talked about it a lot
16:56:39 <acozine> and we seem to start from scratch each time
16:56:58 <samccann> template for /docs folder in collections - requires The Powers That Be
16:57:02 <acozine> yeah
16:57:23 <acozine> we've made progress on 2 out of 6
16:57:26 <acozine> we can try again next week
16:57:31 <acozine> meanwhile . . .
16:57:36 <acozine> #topic docs survey
16:57:51 <acozine> we got 876 responses to the docs survey
16:57:57 <acozine> oops, typoi
16:58:01 <acozine> 867 responses
16:58:06 <samccann> wwoot! and I'll be removing the banner today
16:58:13 <acozine> over 700 of them from the website
16:58:18 <gundalow> gwmngilfen: FYI
16:58:21 <acozine> so way to go samccann with that banner!
16:58:38 <gwmngilfen> gundalow: where do you think those numbers came from? :)
16:58:50 <acozine> heh
16:59:02 <gwmngilfen> but thankyou for inclusion all the same :)
16:59:04 <acozine> more details to come
16:59:25 <acozine> #topic open floor
16:59:33 <acozine> anybody have PRs that need review?
16:59:41 <acozine> issues that have come up?
16:59:48 <gundalow> acozine: Where did those results numbers come from?
16:59:55 <acozine> other ideas/comments/critiques?
17:00:02 <acozine> gundalow: from gwmngilfen, of course!
17:00:12 <gundalow> urrrrrrgh
17:00:31 <gundalow> gwmngilfen: soz, didn't realise that was a rhetorical question
17:00:33 <gundalow> as you were
17:00:34 * gwmngilfen uploaded an image: image.png (50KiB) < https://matrix.org/_matrix/media/r0/download/matrix.org/vjHSOAwOYbhZxCnFAcvObLgL/image.png >
17:01:17 <gwmngilfen> gundalow: EOUTOFCHEESE
17:02:08 <acozine> all right, time for the standard reminders
17:03:17 <acozine> #info if you have question, concern, or idea related to Ansible docs, you can bring it up in the ansible-docs channel at any time, or add it to the DaWGs meeting agenda by adding a comment to https://github.com/ansible/community/issues/579
17:03:37 <acozine> #info everyone is welcome in the channel and in all meetings
17:04:44 <acozine> felixfontein: we're not voting
17:04:54 <acozine> oh good heavens
17:04:55 <acozine> I'm losing it
17:05:00 <acozine> scrolled up
17:05:12 <acozine> and responded to comments from ten minutes ago
17:05:14 <abadger1999> heh :-)
17:05:29 <acozine> thanks abadger1999 bcoca dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro
17:05:36 <gwmngilfen> not just me who struggles with the first day back then
17:05:47 <acozine> gwmngilfen: heh, and this is my second day back
17:06:00 <gwmngilfen> pfft, details
17:06:01 <acozine> maybe more caffeine will help
17:06:11 <gwmngilfen> day, week, month, shrug
17:06:19 <acozine> thanks also gwmngilfen (sorry, I never made you into furniture)
17:06:23 <acozine> oh!
17:06:40 <acozine> samccann: do we have a supplemental meeting for the docsite split on Thursday?
17:07:04 <samccann> yes
17:07:10 <acozine> can you info it?
17:07:21 * acozine can't remember the time
17:07:36 <samccann> #info we will have the supplemental docs meeting on Thurs at 10:30ET to discuss/update on the docsite split
17:07:48 <acozine> thanks again everybody!
17:07:53 <felixfontein> thanks :)
17:07:56 <acozine> see you on Thursday (or next Tuesday)
17:07:58 <felixfontein> (sorry for being not fully attentive...)
17:07:59 <acozine> (or sooner)
17:08:22 <acozine> felixfontein: we all have days like that!
17:08:25 <acozine> #endmeeting