15:00:57 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:57 <zodbot> Meeting started Tue Sep 20 15:00:57 2022 UTC.
15:00:57 <zodbot> This meeting is logged and archived in a public location.
15:00:57 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:57 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:57 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:17 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:25 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
15:01:27 <DonNaro[m]> o/
15:01:28 <briantist> o/
15:01:34 <samccann> #chair Don Naro
15:01:34 <zodbot> Current chairs: Don Naro samccann
15:01:39 <briantist> double+ booked but sort of here
15:01:40 <samccann> #chair briantist
15:01:40 <zodbot> Current chairs: Don Naro briantist samccann
15:01:41 <DonNaro[m]> double booked as usual 😦
15:02:14 <Dhee5096[m]> o/
15:02:18 <samccann> #chair Dhee#5096
15:02:18 <zodbot> Current chairs: Dhee#5096 Don Naro briantist samccann
15:02:22 <samccann> and welcome!
15:02:44 <samccann> We 'chair' people so you are free to add meeting minute items ..should the mood strike you :-)
15:03:14 <samccann> The meeting uses commands like #info to add a sentence to the meeting minutes. You'll see that in action as we move along here today
15:03:23 <samccann> felixfontein: you are to talk docs today?
15:04:36 <acozine> o/
15:04:42 <samccann> #chair acozine
15:04:42 <zodbot> Current chairs: Dhee#5096 Don Naro acozine briantist samccann
15:04:53 <samccann> ok let's get started for realz.
15:05:18 <samccann> official agenda at https://github.com/ansible/community/issues/643#issuecomment-1245659831
15:06:00 <samccann> And as a reminder, if you have a topic to discuss, feel free to add it as a comment on that issue anytime and we can pick it up at the next meeting. Tho we also have an open floor time at the end of this meeting to bring up anything on your mind
15:06:11 <samccann> #topic Action Item updates:
15:06:24 <samccann> #info open - Create tracking issue 'somewhere' to track all the collections that SHOULD consider using true/false boolean in examples (tho some may not want to for $REASONS)
15:07:15 <samccann> #info resolved - merged antsibull-docs update to docs requirements. Will need to schedule remaining requirements updates for later this Autumn
15:07:35 * samccann tries to be more global and not use the local Fall term for... that time of year
15:07:38 <samccann> :-)
15:08:04 <samccann> #info resolved - collection owners fixed a few broken docs links in their Galaxy docsite links etc
15:09:09 <acozine> that all sounds like progress!
15:09:33 <acozine> what's the next step on creating the update-your-boolean-examples issue?
15:09:38 <acozine> figure out where to put the issue?
15:09:40 <samccann> yep. once in a while, we have a productive week (when it comes to nailing those action items
15:09:56 <samccann> So it's multiple issues. like any collection with booleans.
15:10:43 <samccann> So I can create an issue quickly on the community project board, but then we need a big ol checklist of all the collections impacted, and then volunteers to open issues on each of them... etc etc
15:11:45 <samccann> so maybe I create that issue after this meeting, and then in the issue, we can draft the wording. From there, anyone can pick up a collection, create an issue in that repo, and check off that collection in the tracking issue.
15:11:49 <samccann> does that make sense?
15:12:52 <acozine> yeah, I think so
15:12:55 <samccann> As a reminder, the Ansible community decided to use `true/false` for boolean values  instead of other options, like `yes/no` etc.  This makes it compatible with the ansible-lint tool (and yaml 2.1 spec). But it's not a hard requirement.
15:13:14 <samccann> So what WE can do, is recommend.  The collection owner can follow along, or ignore it.
15:13:39 <acozine> to clarify, this is a choice about what to use for boolean values IN THE DOCS, Ansible accepts a wide variety of boolean values
15:13:40 <samccann> ok I'll create the issue and then dump in all the collection names. Some may not have any booleans but it's the easiest way to get started I think
15:13:58 <acozine> yep, sounds good
15:14:33 <samccann> coolness
15:14:37 <samccann> #topic Hacktoberfest
15:15:11 <samccann> #info we hope to participate in Hactoberfest by creating a batch of easy-fix issues to help us clean up the docs. See https://hacktoberfest.com/participation/ for what this is
15:15:53 <samccann> it lasts a month, and we've had great response in the past.  The question for us here -what do we think are the easy things that will help us improve the docs, given a batch of volunteers from around the globe who are looking for free t-shirts :-)
15:16:09 <samccann> so they won't know Ansible. Some may have limited git skills etc.
15:16:29 <samccann> #info initial brainstorming ideas of what we could fix - https://hackmd.io/gNQ2TQW8T4ilcZc8JAM5fQ
15:17:22 <briantist> first off we should ensure all repos who want to participate (or all who don't want to not participate :-p ) have the `hacktoberfest` topic on them
15:17:23 <acozine> if we can get the Big Boolean Update issue ready in time, that seems like a great one for Hacktoberfest
15:17:39 <briantist> I know we did a big update last year, but there may have been new collections included since then
15:18:45 <samccann> acozine: hacktoberfest volunteers only get credit for 'merged' PRs, but if as briantist suggests, the collection repo has hacktoberfest topic and wants to participate, that's definitely possible
15:18:45 <acozine> do we have a page somewhere that lists all included collections for a given version of the Ansible package?
15:19:11 <samccann> acozine: yes the build data... I'm blanking on the formal name but that's where I'll get the list from and stick in that ticket
15:19:34 <samccann> briantist: good idea on letting all the collection owners know. Sounds like a bullhorn item for sure!
15:20:03 <briantist> adding the topic on a repo ensures that maintainers don't need to add a label to each PR accepted; we can put it in the bullhorn, but most of us don't have the permission in the `ansible-collections` organization to add repo topics
15:20:31 <samccann> oh interesting.. didn't know that
15:21:22 <briantist> hm maybe it has changed, it seems I've gained the permission since last year, but I don't know if that's due to other steering committee reasons or what
15:21:28 <samccann> I can ask internally here if anyone on the community team has those rights.  Tho it begs the question = if one of us DOES have the rights, should we put the topic there, or should we still just ask the collection maintainers to put the topic?
15:21:36 <samccann> haha you have the POWER!!!
15:22:09 <briantist> I believe gundalow or another RH employee added the topic in bulk last year, so most probably still have it, but I'm not sure if new additions do
15:22:59 <samccann> #action samccann to ask community team if someone has rights to add hacktoberfest topic to all collections (esp new ones as this was done last year for existing collections)
15:23:00 <briantist> some folks don't like hacktoberfest and have seen lots of spam PRs from people trying to get the t-shirt; it hasn't been my experience but we should probably be aware that some may not want it to be on their repos
15:23:01 <samccann> coolness
15:23:15 <samccann> yeah valid point.
15:23:49 <samccann> #info should also consider some repos won't want to participate in hacktoberfest as it does trigger some 'spam' PRs.
15:24:39 <samccann> We've gotten a few of them the first few days of Hacktoberfest in the past as well, but when we ran it with a bit of forethought, the contributions that came after that initial burst of spam were well worth it
15:25:32 <samccann> ooo
15:25:34 <samccann> oooooooo!!
15:25:39 <samccann> had an idea
15:26:32 <samccann> There are a few issues I've been meaning to open on collections to draw their attention to thinks like the added links for docs, etc. If we open those issues, they are possibly good for the hacktoberfest  categories as well.
15:27:38 <samccann> ok anything else on hacktoberfest before we move on?
15:28:26 <acozine> that's a great idea
15:28:42 <samccann> #topic Documentation updates
15:29:29 <briantist> samccann: one of those things (like links, etc.) could be symlinking the CHANGELOG and adding it to the docsite 😎
15:29:36 <samccann> so one of things that has happened with so many ansible-related projects is that each one is making an independent decision on what markup/down language to use for their docs
15:30:14 <samccann> briantist: do you have the pr handy where you did that?  Was just looking at  the end result and really liked it
15:30:17 <briantist> like this:
15:30:18 <briantist> https://github.com/ansible-collections/community.hashi_vault/pull/299
15:30:18 <briantist> https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/index.html#changelog
15:30:23 <samccann> cool thanks!
15:30:54 <samccann> #action samccann to open issue(s) to suggest collection owners link in their changelogs (such as https://github.com/ansible-collections/community.hashi_vault/pull/299)
15:31:14 <samccann> ok back to markup language fun. We have RST and MD already in our different ansible projects
15:31:32 <samccann> So the general question - does it matter to contributors what is used?
15:31:57 <samccann> we'll probably open a community-topic but wanted to get an initial discussion going.
15:32:23 <acozine> I'd say if we only have two markup languages, we're doing pretty well
15:32:23 <samccann> so like 'would asciidoc be a barrier to contributors if a project used that for their docs?" kind of question
15:32:53 <samccann> heh. yeah. afaik we have two today, but that could grow.  Are we hurting ourselves by not saying THOU SHALT USE RST
15:33:01 <acozine> hm, I would be concerned about adding any new markup languages that require processing before being displayed
15:33:05 <samccann> so it's a consistent experience across projects.
15:33:19 <samccann> I checked, asciidoc displays okay in github already
15:33:41 <samccann> tho I'm sure there are other markup/down that doesn't so valid point
15:33:46 <acozine> okay in GitHub and okay on docs.a.c are different things, though
15:34:04 <samccann> #info IF we have more markup languages for docs in other projects, they must have a reasonable display on github
15:34:28 <samccann> #info any markup has to also display well on docs.ansible.com as a priority
15:35:01 <felixfontein> o/
15:35:10 <felixfontein> sorry I'm only halfway here
15:35:24 <samccann> so yeah, those are good guardrails. But the general question - if you were looking to contribute to the ansible-spiffy project, and saw the docs were in asciidoc, would you walk away, or would you roll up your sleeves and still contribute?
15:35:51 * samccann picking on asciidoc because it's not as common in ansibleland so good example of something 'new to many'
15:35:57 <samccann> #chair felixfontein
15:35:57 <zodbot> Current chairs: Dhee#5096 Don Naro acozine briantist felixfontein samccann
15:36:00 <samccann> welcome welcome
15:37:29 <acozine> I think RST has a good balance between readable and flexible - in other words, it's fairly easy to look at the RST files and figure out how they relate to the final HTML
15:37:39 <acozine> That's frequently not the case for asciidoc
15:38:19 <acozine> and at the same time, RST gives us more ways to control the output and how it looks than plain markdown does
15:39:40 <acozine> so it feels like a good balance - enough tools for folks who know how to use them, enough simplicity for folks who just want to fix a typo
15:40:33 <acozine> anything that leans too far one way or the other (and in my mind, most other tools, including asciidoc, do) makes it hard for one kind of contributor or the other
15:40:46 <samccann> okay to flip the question a bit
15:41:03 <samccann> is it worth FORCING ansible-spiffy to use RST if it already uses say MD for docs?
15:41:16 <samccann> as in how important do we feel is consistency across ansible projects?
15:42:14 <acozine> probably not worth forcing collections to change, but probably worth forcing collections to pick from our current list of two options
15:42:24 <acozine> RST preferred, markdown allowed
15:42:41 <acozine> but that's just one person's opinion
15:43:10 <samccann> yep and thanks. it helps us understand a bit better how to formulate the discussion when we do finally turn it into a community-topic
15:43:42 <samccann> the gist of it is, we'll probably look to add more ansible-related projects to docs.ansible.com, so we want to know what's the best approach to help those other projects gain community contributions etc
15:44:11 <samccann> #info one option - we could recommend RST for ansible projects, but allow MD if it already exists, etc.
15:45:58 <samccann> I probably should have elaborated at the beginning of this topic - but like I said, we have many existing ansible projects where we COULD add the docs to our docsite. We will also likely have new projects in the future, and we could either recommend or mandate what they use for docs.
15:46:57 <samccann> So just trying to understand the impact of either letting each project 'do their own thing', recommend something like RST but allow others, or THOU SHALT USE RST (aka mandate it as a requirement to be part of the ansible docs family)
15:47:20 <samccann> ok we have a few minutes left
15:47:21 <samccann> #topic Open Floor
15:47:30 <samccann> Anyone have something on docs you want to bring up for us today?
15:48:53 <acozine> Dhee#5096: hello and welcome!
15:49:04 <acozine> I'm curious what brought you to the DaWGs meeting?
15:49:22 <felixfontein> +1 for recommending RST but also allowing MD
15:49:40 <acozine> Please introduce yourself, if you're comfortable with that Dhee#5096
15:50:22 <samccann> #info generally leaning toward 'recommending RST but allowing MD
15:51:20 <samccann> I think Dhee#5096 slipped back offline for a bit but they are one of our community-writers!
15:52:14 <samccann> So one topic quickly - how to we make this meeting more 'new contributor' friendly?
15:52:59 <samccann> I feel like we have a lot to discuss each week that gets VERY deep into docsland and docs generation. Which is great, we need those conversations. But just thinking if I wondered into a meeting like this w/o knowing all the background, I'd be lost and likely stay lost
15:53:04 <samccann> (and thus maybe not come back).
15:53:42 <acozine> yeah, this does tend to be something of an experts' summit, at least many weeks
15:54:11 <acozine> maybe we could highlight a docs PR each week, to give new folks an example of what they could do/try?
15:54:13 <samccann> would it be worth having say a separate 'docs office hours' or something?
15:54:43 <acozine> that's a fun idea
15:54:46 <samccann> cuz yeah we definitely need the experts summit we have here regularly :-).
15:55:20 <samccann> ok might try that then. an open docs hr later in the week
15:56:18 <samccann> #action samccann to consider an 'open docs hr' later in the week to regularly interact with docs contributors in a friendlier way than the expert details that happen in DaWGs meetings
15:57:01 <acozine> that should be considered a DaWGs meeting too, just one with a different focus, maybe
15:57:15 <acozine> all contributors to docs are DaWGs members!
15:57:19 <samccann> #info consider it as a possible optional separate DaWGs meeting
15:57:20 <briantist> the agenda issue should have an intro/welcome/here's what you need to know as a new attendee thing
15:57:38 <samccann> oh nice briantist !!
15:57:41 <briantist> so that newcomers can prepare leading up to it or in the background
15:58:07 <briantist> that could actually be a separate page that;s just linked from that issue
15:58:34 <samccann> #action samccann -t to add a link to a separate intro to the agenda for welcome/here's what you need to know/ etc so newcomers can prepare.
15:58:48 <samccann> great idea! We do have a docs wiki off in github land we could add that to
15:59:34 <samccann> ok that's about time here unless anyone has something to add?
16:00:28 <acozine> thanks samccann for running the meeting!
16:00:28 <samccann> #endmeeting