14:31:53 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:53 <zodbot> Meeting started Tue Dec  8 14:31:53 2020 UTC.
14:31:53 <zodbot> This meeting is logged and archived in a public location.
14:31:53 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:53 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:53 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:59 <acozine> #topic opening chatter
14:32:12 <acozine> #chair baptistemm samccann lmodemal dmsimard gundalow
14:32:12 <zodbot> Current chairs: acozine baptistemm dmsimard gundalow lmodemal samccann
14:32:13 <tadeboro> Hi all.
14:32:18 <acozine> hi tadeboro
14:32:22 <acozine> #chair tadeboro
14:32:22 <zodbot> Current chairs: acozine baptistemm dmsimard gundalow lmodemal samccann tadeboro
14:32:27 <acozine> who else is around?
14:32:33 <gundalow> Oh, before I forget, abadger1999 asked if this could be moved later in the day so he could attend
14:32:36 <aminvakil> hello everyone
14:32:40 <acozine> hi aminvakil
14:32:43 <acozine> #chair aminvakil
14:32:43 <zodbot> Current chairs: acozine aminvakil baptistemm dmsimard gundalow lmodemal samccann tadeboro
14:33:01 <dmsimard> gundalow: we discussed it briefly last week
14:33:11 <acozine> tadeboro: baptistemm I know you two are in Europe and you regularly attend
14:33:27 <acozine> is there a time later in the day when you'd be available?
14:34:44 <gundalow> dmsimard: oh, must have missed it
14:35:03 <tadeboro> Moving this is not problematic for me since most of other Ansible-related stuff is usually scheduled later as well.
14:35:04 <acozine> we did mention it
14:35:12 <acozine> baptistemm: what about you?
14:35:25 <tadeboro> It feel weird to talk Ansible stuff before dinner ;)
14:35:31 <tadeboro> feels*
14:35:37 <gwmngilfen> o/
14:36:01 <acozine> felixfontein: I know you're not here for the meeting but if you see this, please comment on how happy/unhappy you would be about pushing this meeting a bit later
14:36:07 <acozine> #chair gwmngilfen
14:36:07 <zodbot> Current chairs: acozine aminvakil baptistemm dmsimard gundalow gwmngilfen lmodemal samccann tadeboro
14:36:36 <dmsimard> iirc in ~1h30 would be the earliest possible for badger
14:36:43 <dmsimard> 8am pst
14:37:30 <acozine> yeah, the current time is 8:30AM for me, 6:30AM for him
14:38:21 <cybette> o/
14:38:32 <acozine> #chair cybette
14:38:32 <zodbot> Current chairs: acozine aminvakil baptistemm cybette dmsimard gundalow gwmngilfen lmodemal samccann tadeboro
14:38:37 <acozine> big group today!
14:38:41 <tadeboro> In CEST, we are at 3:30PM right now. So moving things for an hour or two does not make much difference for me.
14:39:01 <tadeboro> *CET (forgot it is december already)
14:39:07 * dericcrago waves
14:39:11 <acozine> #chair dericcrago
14:39:12 <zodbot> Current chairs: acozine aminvakil baptistemm cybette dericcrago dmsimard gundalow gwmngilfen lmodemal samccann tadeboro
14:39:42 <samccann> #topic changing meeting time
14:39:47 <acozine> heh, thanks samccann
14:40:35 <samccann> #info for some regular attendees - this current time is problematic. Seems later in the day (ET) would work better
14:40:39 <acozine> if we change it, we need to update https://github.com/ansible/community/wiki/Docs
14:40:45 <baptistemm> sorry, my new job gives me little time now
14:40:55 <samccann> congrats on the new job!
14:41:13 <gundalow> baptistemm: You never have to appologise for that. Congratulations on your new job :)
14:41:20 <baptistemm> the great thing is they use ansible
14:41:29 <acozine> baptistemm: sounds wonderful, congrats
14:41:55 <aminvakil> congratulations baptistemm!
14:42:31 <cybette> congrats baptistemm !
14:43:17 <acozine> thanks for joining today baptistemm, we're happy to see you here any time
14:43:47 <acozine> gundalow: where is the main "all the working groups' meetings" page?
14:43:50 <baptistemm> acozine: I'm connected all the time :)
14:43:56 <felixfontein> during winter time, 1:30 later is fine for me. in summer it would not be so great :)
14:44:16 <acozine> felixfontein: thanks
14:44:21 <dmsimard> in summer I suspect we'd rewind back not unlike what we did for ansible-community
14:44:32 <gundalow> acozine: https://github.com/ansible/community/tree/main/meetings
14:44:46 <gundalow> Yes, I'd expect we revert the change once all the clocks have changed
14:45:11 <felixfontein> (off again)
14:45:17 <acozine> yeah, in summer the usual time is easier - among other things it's light in the morning, which makes 7:30 more cheerful than 6:30 in the dark
14:45:25 * acozine waves at felixfontein
14:45:49 <samccann> so do we push out 1.5 hrs, or 1hr to match what community did?
14:46:07 <acozine> I'd vote for 1.5 hours, only because that way I might remember the difference
14:46:22 <samccann> heh
14:46:30 <acozine> if we do a whole-hour(s) change, I will just figure it out when we change back again
14:46:52 <samccann> 1.5 would be easier I'd guess on abadger and any other west-coast-us folks
14:46:57 <acozine> but I'm only one vote
14:47:30 <samccann> time for a.... VOTE?
14:47:42 <acozine> VOTE: +1 to start this meeting 1.5 hours later during the winter
14:47:47 <dmsimard> +1
14:47:50 <tadeboro> +1
14:48:20 <gundalow> +1
14:48:26 <acozine> #chair
14:48:26 <zodbot> Current chairs: acozine aminvakil baptistemm cybette dericcrago dmsimard gundalow gwmngilfen lmodemal samccann tadeboro
14:48:35 <aminvakil> +1
14:48:37 <acozine> votes encouraged on ^^^
14:48:45 <samccann> +1
14:48:47 <dericcrago> +1
14:49:36 <dericcrago> can / should someone proxy a vote for abadger1999? :)
14:49:55 <acozine> this would be 16:00 UTC and we would revert to 14:30 UTC when the clocks change in spring
14:50:26 <acozine> +1
14:50:57 <acozine> dericcrago: we'll add T's vote to the total
14:51:04 <lmodemal> +1
14:51:35 <acozine> so far it's +9, no 0s, no -s
14:52:05 <acozine> so three non-voters
14:52:39 <acozine> #agreed DaWGs meeting to move to 16:00 UTC for the winter, revert to 14:30 UTC in spring
14:53:36 <acozine> #action update https://github.com/ansible/community/tree/main/meetings and https://github.com/ansible/community/wiki/Docs to reflect this change
14:53:38 <gundalow> \o/
14:54:34 <dmsimard> btw we have the meeting time in the IRC channel topic on #ansible-community now
14:54:47 <dmsimard> maybe we can put it here too :p
14:54:48 <tadeboro> So I guess we start in an hour? ;)
14:55:03 <samccann> LOL!!
14:55:24 <acozine> tadeboro: it's too early for Groundhog Day
14:56:11 <acozine> or maybe 2020 has been one long Groundhog Day?
14:56:24 <lmodemal> lol
14:57:14 <acozine> #topic formatting for options in module docs
14:57:17 <acozine> https://github.com/ansible/community/issues/521#issuecomment-739263018
14:57:56 <acozine> I'm not sure why, but traditionally we've formatted `my_option: this_value` in italics instead of in code
14:58:08 <acozine> hm, how do you do italics in IRC?
14:58:23 <dmsimard> I do /like this/
14:58:52 <dmsimard> not really italic but heh
14:59:28 <acozine> anyhow, this came up on a PR recently
14:59:54 <dmsimard> screenshot of different proposals by felixfontein: https://user-images.githubusercontent.com/5781356/101246103-6b5a8c00-3711-11eb-95a3-ceeff22ea9b4.png
15:00:03 <tadeboro> When documenting stuff, I usually do something like: "... if I(property) is set to C(value) ..."
15:00:05 <acozine> and my only answer to "why don't we make those look like code?" was "we've always done it that way", which is a stupid answer
15:00:44 <dmsimard> tadeboro: so the name of the option as italic and then the value of the option as code
15:00:51 <acozine> tadeboro: that's consistent and probably looks good, but we have a lot of "When I(prop: val) do X"
15:01:04 <dmsimard> which is #3 on that screenshot (is #4 not different or is that just me)
15:01:06 <acozine> ^^^ already in the module docs
15:01:31 <dericcrago> 3 & 4 are hard to tell the difference, but #3 has the `=` in italics as well
15:01:50 <dmsimard> eh
15:02:01 <tadeboro> I would say that "prop: val" is all in C() because it is a (very short) playbook snippet.
15:02:10 <acozine> the argument that made sense to me is "if someone would be likely to copy and paste something, we should format it as code"
15:02:30 <samccann> we have two sources we could go to - IBM Style Guide and RH style... do we want to follow 'whatever they do'?
15:02:49 <acozine> could it be possible that they would agree???
15:03:13 * samccann checking ibm style guide
15:03:22 <acozine> if they both say the same thing, that's a strong argument for doing what they do
15:03:35 <tadeboro> acozine: Of course not. What is possible is to create a third one that disagrees with both of them ;)
15:03:46 <dmsimard> xkcd-standards.jpg
15:03:56 <acozine> tadeboro: oh, of course, sorry . . . what was I thinking?
15:04:40 * tadeboro is not familiar with RH and IBM guides, so there is still hope
15:04:59 <samccann> looks like IBM style guide has *bold* for the parameter name (aka option) and teletype  for the value
15:05:24 <dmsimard> samccann: do you have a source even if just for reference ?
15:05:26 <samccann> https://usercontent.irccloud-cdn.com/file/V6uX3I1x/image.png
15:05:45 <dericcrago> if we didn't do `option=value` I'd maybe lean towards **option**=`value`     ** = bold in this case
15:06:00 <samccann> ^^ that matches IBM style guide
15:06:00 <tadeboro> I know I had to follow some guide when authoring ManageIQ documentation, but I cannot remember what we did there. Let me see if I can find a sample document.
15:07:57 <samccann> the RH supplemental style guide doesn't cover this, which means RH docs should follow the IBM Style guide in this instance
15:09:33 <tadeboro> Our ManageIQ/CFME docs use bold for both variable names and values.
15:10:05 <dmsimard> FWIW the options are already bold in the parameter columns, i.e https://docs.ansible.com/ansible/latest/collections/ansible/builtin/package_module.html
15:10:06 <samccann> dmsimard - if you were asking for a source for the IBM Style guide - it's something that is purchased for each writer here in RH
15:10:17 <dmsimard> samccann: *purchased* ?
15:11:03 <samccann> dmsimard - my department buys the license for X many pdfs and gives one to each writer.
15:11:03 <gundalow> Current standard is defined here https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#linking-and-other-format-macros-within-module-documentation
15:11:55 <acozine> gundalow: you beat me to it
15:12:01 <gundalow> acozine: :)
15:12:02 <tadeboro> Heh, example for option name uses name and value ;)
15:12:31 <acozine> yeah, and that's very common in the module docs
15:14:04 <acozine> "Required if var=value"
15:15:00 <samccann> usual disclaimer applies - whatever format we change to, we need to inform the Galaxy team of so they can consider making the same change (or not)
15:15:01 <acozine> so we'd be changing `I(var=value)` to `B(var)=C(value)`
15:15:07 <tadeboro> I usually write this as "Required if I(var) is C(value)"
15:16:17 <acozine> tadeboro: do you strongly prefer italics to bold in this case?
15:16:51 <samccann> #info IBM style guide would format this as bold for the option and teletype for the value. Using our current format types, this would be B(var)=C(value)
15:16:54 <tadeboro> Do not care at all. I just used what most modules that used my preferred wording used.
15:17:24 <acozine> samccann: Galaxy team? for collections?
15:17:39 <samccann> for how they render module docs in AH/galaxy-ng
15:17:49 <acozine> samccann: ah, okay
15:18:09 <samccann> they don't HAVE to match what we do, but I think they started out  that way at least. So an FYI for them to consider
15:18:30 <samccann> does this formatting show up in `ansible-docs` as well?
15:18:45 <acozine> if we change the underlying text, it should be easy for them to update how it looks . . . at least, I hope so
15:19:00 <acozine> ah, good question
15:19:57 <dmsimard> I just checked two different modules in ansible-doc and I don't see any bold/italic/monospace
15:19:59 <samccann> again, not a showstopper - just someone else we need to inform of any format changes
15:20:17 <samccann> ok cool, thanks!
15:22:20 <tadeboro> I quickly check a few collections on AH and they all seem to use I(param) for parameter names, C(val) for values, and C(param=val).
15:22:38 <dmsimard> so felixfontein has four options in his comment and I there is a fifth option to consider: B(option)=C(value)
15:22:41 <tadeboro> No bold thing in sight.
15:22:52 <acozine> heh, of course not
15:23:01 <dmsimard> shall we vote or should we perhaps have a better test to help us vote on at a later date ?
15:23:21 <dmsimard> by better test I mean test rendering an example module page with all five options before voting
15:23:23 * gundalow -> afk
15:24:04 <gundalow> You'll need to update all the DOCUMENTATION entries in every module to use the new format
15:24:30 <acozine> yes, we'd need to do that, though we could do it over time
15:24:31 <tadeboro> Five options? I only know about two: terminal output for ansible-doc and rst renderer. Is there anything else?
15:24:56 <dmsimard> tadeboro: I was referring to the options laid out in https://github.com/ansible/community/issues/521#issuecomment-739263018
15:25:22 <acozine> the main thing is, if we have a standard, we should document it correctly, then we can (slowly or not-so-slowly) bring our existing documentation into compliance
15:25:24 <tadeboro> dmsimard: Ahh, that makes more sense, indeed ;)
15:25:54 <acozine> dmsimard: would you be willing to do that sample module work for next week's meeting?
15:26:04 <dmsimard> sure
15:26:05 <acozine> that sounds like a good idea
15:26:18 <samccann> so I think the problem is = the current italics is harder to read.  The 'officially sanctioned' solution is B(option)=C(value)
15:26:37 <dmsimard> #action dmsimard to draft 5 example renders of options in https://github.com/ansible/community/issues/521#issuecomment-739263018 + B(option)=C(value) to help vote at a later meeting
15:26:49 <samccann> The 'quick n dirty' solution would be to to change I() to teletype and call it a day (easier to read)
15:27:08 <dmsimard> what is "teletype" ? is that monospaced code ?
15:27:12 <acozine> the other problem is that `option=value` could be copy/pasted into a playbook, so in that sense the entire phrase is code
15:27:45 <acozine> which supports samccann's solution as well
15:27:46 <tadeboro> acozine: That last example is not the best candidate for copy-pase since YAML usually uses ":" to delimit key and value.
15:27:56 * dmsimard has opinions about using ='s in playbooks instead of pure yaml
15:27:57 <acozine> erg, sorry
15:28:04 <acozine> I still do that
15:28:11 <acozine> old bad habits are hard to break
15:28:45 * acozine tries again
15:29:06 <acozine> folks might copy/paste `option: value` into a playbook
15:29:18 <acozine> and it's happened again . . .
15:29:28 <acozine> I picked something I thought would be really quick
15:29:31 <samccann> heh
15:29:33 <acozine> that turned out not to be quick at all
15:29:49 <acozine> and we're at the hour for today's meeting
15:29:54 <dmsimard> we could even rabbithole into discussing whether we should use "=" or ":"
15:30:05 <acozine> dmsimard: we should use `:`
15:30:10 <samccann> ok so IBM style guide sez monospace for all of it if it's meant to be copy/pasted
15:30:21 <acozine> samccann: it does? that's great!
15:30:24 <samccann> aka C(option: value)
15:31:15 <acozine> if there are old-style `=` in the docs, we should work to convert them
15:31:20 <samccann> yeah for all examples and cold examples
15:31:32 <acozine> heh, cold examples?
15:31:40 <samccann> haha sorry.. i'm COLD TODAY
15:31:45 * samccann goes and cranks up the heat
15:32:58 <tadeboro> That IBM guide sounds sensible. Adopting it does not sound bad at all to be honest.
15:33:14 <acozine> I agree
15:33:39 <samccann> so I think my nickel vote would be we change the guidelines to C(option: value). Then we figure out how to change 3k modules to match ..?
15:34:13 <dmsimard> let's reconvene on the topic next meeting with rendered examples
15:34:28 <acozine> dmsimard: sounds good
15:34:36 <acozine> #topic quick updates
15:34:38 <samccann> can you add that to your rendering examples?
15:34:50 <dmsimard> samccann: the = vs : ?
15:35:10 <samccann> dmsimard, no the C(option: value)
15:35:40 <dmsimard> sure
15:35:40 <samccann> I think the = needs to be taken out behind the shed and... BLAM
15:37:09 <acozine> we have a bunch of long-running items on the agenda
15:38:07 <acozine> some of them are related to the Version Division (ansible 3.0 / ansible-core 2.11) which we'll discuss again on Thursday
15:38:25 <acozine> * use of the `/docs/` folder in a collection
15:38:41 <acozine> * docs for filter and test plugins
15:39:00 <acozine> * redirects for module docs
15:39:24 <gwmngilfen> survey is going well so far, if anyone is interested. 120 replies as of this morning. is there an ETA for it going on the website?
15:39:36 <acozine> gwmngilfen: ah, thanks
15:40:13 <acozine> we could possibly get it added to a website banner this week
15:40:25 <acozine> for everyone here
15:40:40 <acozine> we have different links TO the survey
15:41:03 <acozine> so we can track differences in, for example, people who saw the link on Reddit vs. people who saw it in The Bullhorn
15:41:13 <samccann> gah sorry forgot
15:41:31 <samccann> #action samccann add survey to ansible banners for latest/devel
15:41:48 <samccann> do we have a link specific for the docsite?
15:41:53 <gwmngilfen> mostly it's not a big deal, but sometimes it provides interest
15:41:56 <gwmngilfen> yes
15:42:15 <gwmngilfen> https://www.surveymonkey.co.uk/r/B9V3CDY is the one for the website
15:43:21 <acozine> cybette publicized it on Twitter
15:43:43 <acozine> for those who have Twitter accounts, feel free to re-tweet!
15:43:57 <aminvakil> sorry i have to go now, and i couldn't concentrate on docs today at all because of latest surprise redhat has done (https://blog.centos.org/2020/12/future-is-centos-stream/)
15:44:06 <acozine> aminvakil: thanks for coming
15:44:12 <aminvakil> thank you!
15:44:14 <acozine> good luck with your surprise
15:44:39 <cybette> yep, and I will schedule a couple more tweets to go out for the survey this month
15:44:58 <acozine> cybette: thank you, that's awesome
15:45:11 <gwmngilfen> how long do you want to run it for?
15:45:19 <acozine> we will keep the survey open through Dec. 31st
15:45:42 <acozine> gwmngilfen: unless you think that is Far Too Long or Far Too Short a time?
15:45:55 <gwmngilfen> its fine. although I will will be PTO then
15:46:12 <gwmngilfen> i can close it when I get back, but feel free to stop promoting it then
15:46:22 <acozine> ah, so we'd have to learn the SurveyMonkey magic to turn it off before you come back?
15:46:30 <acozine> how long into Jan are you on PTO?
15:46:33 <gwmngilfen> well its not lik i'm going far ....
15:46:37 <gwmngilfen> *like
15:46:54 <gwmngilfen> lemme see if i can set an autoclose
15:47:14 <gwmngilfen> ah yes
15:47:14 <acozine> cool, thanks
15:47:22 <acozine> okay, last plug from me:
15:48:24 <acozine> we've been talking for several weeks (months?) about how to make our documentation reflect both Ansible 3.0.0 and ansible-core 2.11, with any differences between them
15:48:48 <acozine> a lot of these conversations have started to feel circular
15:48:59 <acozine> we come up with ideas, then find blockers
15:49:16 <acozine> the blockers take up back to earlier ideas, which lead to other blockers
15:49:20 <acozine> it's frustrating
15:49:24 <acozine> and time is short
15:50:30 <acozine> so . . . our latest attempt to find a way forward is another document: https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ
15:50:51 <acozine> it's a list of All The Problems, with a few suggested solutions/ideas
15:51:27 <acozine> all DaWGs welcome to comment and/or add to the text
15:52:01 <acozine> if you remember problems or blockers not listed there already, please add them
15:52:15 <acozine> if you read it and think of new problems or blockers, add those too!
15:52:57 <acozine> and if you can, join us on Thursday at 15:00 UTC here to talk about The Future Of Ansible Docs
15:54:00 <acozine> #info supplemental meeting on Thursday Dec. 10 at 15:00 UTC
15:54:14 <acozine> #info review https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ beforehand if possible
15:55:07 <acozine> gwmngilfen: thanks for figuring out the end date for SurveyMonkey
15:55:17 <gwmngilfen> all are set for 11.45 pm
15:55:38 <gwmngilfen> i hate "midnight" as it's never clear if thats the start or the end of the day
15:55:54 <acozine> yes, that is confusing
15:56:12 <acozine> and 23:45 makes it clear
15:56:13 <gwmngilfen> https://yourcalendricalfallacyis.com/
15:56:57 <acozine> heh
15:56:58 <gwmngilfen> thats a long read, but a lot of fun
15:57:09 <acozine> and we've run a half-hour over
15:57:15 <samccann> heh
15:57:15 <gwmngilfen> also somewhere i have a link about about how bad the Roman's were at calendars, but i digress
15:57:23 <samccann> AAAHAHAHA
15:57:27 <lmodemal> lol
15:58:07 <gwmngilfen> oh, here it is
15:58:08 <gwmngilfen> https://elekk.xyz/@noelle/99213354254637980
15:58:23 <gwmngilfen> another long but entertaining read. get tea
15:58:28 <acozine> we kinda treated the quick updates as open floor, but we'll do an official one as well
15:58:34 <acozine> #topic open floor
15:59:22 <acozine> all questions, comments, suggestions, PRs, and issues welcome
16:00:31 <acozine> gwmngilfen: I'd be in favor of just not talking much about the weeks between December and March
16:00:58 <gwmngilfen> in general, or just the ones in 2020?
16:01:59 <acozine> either way
16:02:32 <acozine> remember that I live in the Upper Midwest, aka the Frozen Tundra
16:02:42 <acozine> not a lot goes on between December and March here
16:03:11 <acozine> but we can keep chatting about calendars and clocks after closing the meeting
16:03:17 <acozine> any open floor topics?
16:03:19 <gwmngilfen> :)
16:03:35 <acozine> going once
16:03:43 <acozine> going twice . . .
16:04:09 <acozine> "Sold!"
16:04:16 <lmodemal> haha!
16:04:17 <acozine> thanks  aminvakil baptistemm cybette dericcrago dmsimard gundalow gwmngilfen lmodemal samccann tadeboro
16:04:28 <gwmngilfen> acozine++
16:04:28 <acozine> #endmeeting