15:01:05 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:05 <zodbot> Meeting started Tue Jun 28 15:01:05 2022 UTC.
15:01:05 <zodbot> This meeting is logged and archived in a public location.
15:01:05 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:05 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:05 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:14 <acozine> it's time to light the lights?
15:01:23 <samccann> #topic opening chatter
15:01:28 * acozine hums the Muppets theme quietly
15:01:30 <DonNaro[m]> this is it, we'll hit the heights
15:01:38 <samccann> heh
15:01:47 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:49 <DonNaro[m]> o/
15:01:56 <acozine> o/
15:01:57 <gundalow> Not around for today's meeting. I'll skim scroll back later on
15:02:07 <samccann> #chair Don Naro acozine
15:02:07 <zodbot> Current chairs: Don Naro acozine samccann
15:02:08 <acozine> gundalow: we'll miss you!
15:02:14 <briantist> kinda here, pretty distracted unfortunately
15:02:31 <samccann> #chair briantist
15:02:31 <zodbot> Current chairs: Don Naro acozine briantist samccann
15:02:32 <DonNaro[m]> I'm here with the caveat that I'll need to drop off at half past but will catch up later
15:02:50 <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:03:01 <acozine> felixfontein: you around today?
15:03:01 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1161936659
15:03:53 <samccann> #topic Documentation updates
15:04:29 <feyo[m]> o/ just here to lurk
15:04:47 <samccann> #chair feyo ⚡️ welcome!
15:04:47 <zodbot> Current chairs: Don Naro acozine briantist feyo samccann welcome! ⚡️
15:04:53 <samccann> everyone gets a chair ;-)
15:05:22 <samccann> So let's start with:
15:05:23 <samccann> #info Userguide getting a facelift! https://github.com/ansible/ansible/issues/78082#issuecomment-1159185553
15:05:42 <samccann> That has the details, but you can see the start of it at https://docs.ansible.com/ansible/devel/index.html
15:05:54 <acozine> lurking is more comfortable with a chair!
15:05:57 <samccann> This is Don Naro 's party! (aka he's doing all the work)
15:06:53 <cybette_> o/ also lurking, since there are so many cool people here
15:07:16 <samccann> #chair cybette welcome welcome
15:07:16 <zodbot> Current chairs: Don Naro acozine briantist cybette feyo samccann welcome welcome! ⚡️
15:08:21 <acozine> do you have a link to the PR?
15:08:32 <acozine> this looks like great stuff!
15:08:44 <samccann> There are multiple. let me check as I think most have been merged on this first file shuffle
15:08:54 <DonNaro[m]> https://github.com/ansible/ansible/pull/78097
15:09:01 <DonNaro[m]> https://github.com/ansible/ansible/pull/78099
15:09:08 <DonNaro[m]> https://github.com/ansible/ansible/pull/78103
15:09:45 <DonNaro[m]> those are the three I've got so far. I would like to tackle the playbooks topics next.
15:10:32 <DonNaro[m]> but it might be too big a change. I'm not sure. tbh I'm still on the learning curve with Ansible and I don't want to move things that don't logically go together.
15:10:57 <DonNaro[m]> although I'm sure samccann will graciously correct me in the PR queue
15:11:20 <samccann> heh well when it comes to the deeper stuff, we may need more reviewers.
15:11:45 <samccann> But this is all just staying in devel until ansible-2.14 releases so we have time to make adjustments etc
15:12:16 <cybette_> great stuff Don Naro  and samccann !
15:12:37 <DonNaro[m]> should we maybe go out and try to get some feedback from the likes of Reddit? they didn't really respond to the Getting Started with Ansible changes but we could try.
15:13:47 <samccann> Don Naro: Sure we could! At what point? Before or after you separate out things like playbooks and inventory etc?
15:14:20 <acozine> Don Naro: my bet is that getting feedback on Getting Started stuff is hard, because those topics are most useful for beginners, but they don't know enough to offer feedback on the docs
15:14:38 <DonNaro[m]> acozine: true
15:15:19 <DonNaro[m]> samccann: Yes I think it might be better to wait and solicit feedback when we've made a bit more progress so we don't have to go back again.
15:15:26 <thedoubl3j> o/
15:15:33 <thedoubl3j> apologies for the tardiness
15:15:56 <samccann> #chair thedoubl3j welcome welcome!
15:15:56 <zodbot> Current chairs: Don Naro acozine briantist cybette feyo samccann thedoubl3j welcome welcome! ⚡️
15:16:22 <samccann> anything else on the userguide revamp before we shuffle on?
15:17:21 <acozine> I'll take a look at the PRs, this week or next
15:18:05 <samccann> cool. So far it's just moving the files, no real edits TO the files. And Don put stubs in the old files for now, but we'll put in redirects once it's all done and in their final homes so to speak.
15:18:47 <samccann> meanwhile...
15:18:48 <samccann> #info - if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
15:19:20 <samccann> ^^ applies for collection owners as well if that wasn't clear. We can add your docs PRs for editor review to that board etc.
15:19:50 <samccann> and one more plug for help:
15:19:52 <samccann> #info always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
15:19:56 <samccann> ;-)
15:20:26 <samccann> We are doing well on chiseling away at that backlog!
15:20:39 <acozine> W00t!
15:20:45 <thedoubl3j> I have a few from the backlog assigned to me, if folks want those, take em, still working on persuading that external contributor I promised you samccann
15:21:00 <samccann> lol thanks for the help!
15:21:12 <thedoubl3j> wanted to get the low hanging fruit to entice them in
15:21:23 <acozine> easyfix hoarding!
15:21:28 <samccann> AHAHAHAH
15:21:44 <thedoubl3j> gotta get those contrib numbers somehow right?? xD
15:22:12 <samccann> tell them badges are here (or coming) - so extra fun when they contribute
15:22:55 <DonNaro[m]> any stickers going? I'm pretty easy to motivate if you offer me stickers.
15:23:21 <samccann> lol! We used to have DaWGs stickers. dunno if we have any left acozine ??
15:23:42 <thedoubl3j> I have one ;) still need to find the right spot for it.
15:23:45 <acozine> erm, I'm sure they're here somewhere
15:23:53 <thedoubl3j> those are high valued stickers.
15:24:06 <samccann> my laptop has mine, but it will need to be replaced soon, so... gonna try peeling it off!
15:24:09 <acozine> but since we moved, "somewhere" got a little less well-defined
15:24:14 <samccann> hehe
15:24:34 <thedoubl3j> We are finishing that process now acozine and I concur big time with that.
15:24:46 <samccann> ok onto the next topic...
15:24:47 <samccann> #topic doctools
15:24:56 <samccann> #info - Need reviews for  canonical URL in Ansible 2.3 https://github.com/ansible/ansible/pull/78135
15:25:29 <cybette_> I might have a couple of DaWGs stickers, and can print more if needed!
15:25:38 <samccann> I did get 2.3 to publish to test so I think we are good to go once we get reviews and merge that PR. It's not a magic fix for google, but will help drive traffic to latest docs instead over  time
15:26:03 <acozine> wow, congratulations on publishing 2.3
15:26:03 <samccann> cybette: cool! Somewhere I have the original artwork I can pass on. Might be time for a reprint!
15:26:54 <samccann> We still havea goal to create a docs archive site and move all the old docs over to that.
15:27:43 <DonNaro[m]> sorry everyone but I need to run. samccann I'll def take a look at that canonical URL PR later. had some questions so I'll ping you. I'll catch everything else in the meeting minutes. thanks again all and take care until next time...
15:27:57 <cybette_> thanks Don Naro !
15:28:00 <samccann> thanks Don Naro
15:28:14 <samccann> #info Do we need to back out the docs override for boolean values? - https://github.com/ansible-community/community-topics/issues/116
15:28:32 <samccann> This came up yesterday and thanks to feyo ⚡️ for summarizing it all in that issue
15:28:44 <samccann> We currently force yes/no for boolean options in the module docs parameter tables, but we aren't consistent with examples, text in those same docs. yes/no also causes errors for ansible-lint (tho that is a wider debate).
15:29:28 <samccann> So from the docs perspective, way back when (2018) we wanted boolean use to be consistent. We chose yes/no because it seemed more friendly to non-programmers than true/false
15:29:40 <acozine> I believe the current code overrides ANY boolean options with `yes/no` in the published docs on docs.ansible.com
15:30:01 <samccann> only in the generated stuff. It doesn't change examples or text afaik
15:30:17 <acozine> so the underlying docstrings may contain any legal boolean (yes/no, 1/0, true/false, etc.)
15:30:21 <acozine> yeah, exactly
15:30:27 <samccann> I put an example of it up on that issue where we changed the value to yes/no, but the description of the option still says true.
15:31:04 <samccann> So I'll be honest, I part of me wants to remove the override so that docs is 'out of the business' of saying what is the preferred values.
15:31:15 <samccann> Then the coders can battle it out :-)
15:32:43 <acozine> yeah, it's a weird thing - on the one hand, it's nice to have consistency, and the current system allows coders to do whatever they prefer in their local docstrings; on the other hand, folks who want to "do what the docs do" get that ansible-lint error
15:33:06 <acozine> and that is annoying and frustrating and feels just plain wrong
15:33:28 <acozine> when you add in the fact that other ways of parsing those docstrings give you different results
15:33:32 <acozine> well, it's a mess
15:33:36 <feyo[m]> so that was basically my viewpoint. i kind of felt like I didnt know which i should do. follow docs or follow ansible-lint on this.
15:33:45 <samccann> yeah that's the bigger issue that has to be solved somewhere else..steering committee or architects or .. who knows. But it's a longstanding painpoint for users for sure
15:34:06 <feyo[m]> i understand its technically not wrong either way, but its a strange thing to have
15:34:23 <acozine> when we chose the current path, I think there were 2 arguments that kinda led the discussion:
15:34:49 <acozine> one was, if we have to confuse some group of people, it's better to confuse new users than developers
15:35:26 <acozine> and the other was, we don't control ansible-lint, so we can't "fix it for real" (because this was before ansible-lint moved its repo)
15:35:45 <acozine> but now we DO control ansible-lint (sort of, at least) and we're still confusing people
15:36:30 <acozine> we also had a very active community member at that time who had very strong views and a very loud voice
15:36:31 <cybette_> probably confusing more after the repo move :P
15:36:38 <feyo[m]> thats why i brought it up in the community working group at first because in the end I agree that consistency is best, but currently the two ansible projects arent consistent between each other
15:36:54 <samccann> The problem is there isn't agreement on ansible-lint's 'role' in the Ansible project. Today it seems enterprise-focused, which is great.
15:36:59 <acozine> feyo ⚡️: yes, and I think it's probably time to try a different approach
15:37:29 <acozine> but a little history helps us all understand how we got to where we are
15:37:36 <acozine> and maybe why change could be a good thing
15:37:49 <samccann> But ansible itself doesn't 'need' to limit boolean to true/false, etc. There are other rules as well that are limiting from the raw ansible perspective
15:38:10 <samccann> ansible.. RAW AND UNCUT! heh
15:38:29 <feyo[m]> so one thing that was mentioned in the ansible-lint PR about this issue is that ansible might move to yaml 1.2 in the future
15:38:35 <samccann> well if you have other thoughts/notions etc please add them to the issue
15:38:35 <feyo[m]> and that yaml1.2 enforces true/false
15:38:41 <feyo[m]> how true is that?
15:38:52 <acozine> heh, it's at least truthy
15:38:53 <samccann> That alas we don't know here personally.
15:39:34 <samccann> But I did see an older closed issue/pr where it was said even when that happens, it would make ansible incompatible with other yaml versions (and that might not be a good thing?) dunno.
15:39:53 <acozine> feyo ⚡️: I'm curious, would you prefer to see all the docs read `true/false`? Or would you prefer to publish the underlying inconsistent values, whatever they might be?
15:40:40 <feyo[m]> if you ask me, Id prefer docs/lint being consistent in general. but id be ok with docs staying out of that fight as mentioned above as well. (and being inconsistent in itself)
15:40:57 <feyo[m]> at least it wouldnt seem like the docs say "yes/no is correct" and ansible-lint saying a different thing
15:41:38 <feyo[m]> in general I think being consistent over the different official ansible projects would be better for new users as well
15:42:00 <feyo[m]> but as was mentioned before, that is a rather larger discussion
15:42:24 <acozine> yeah, wider consistency would be wonderful, though the docs team can only change the docs output
15:42:38 <samccann> So the problem with forcing anything in docs is we can't be consistent. It only changes the parameter choices listed to yes/no (or true/false). If the description or examples say something else, that makes things worse imo and is reason enough to back out  that override.
15:44:12 <thedoubl3j> lint also will be enforcing a built in set of best practices. best practices doesn't always overlap with what the tool (ansible) might accept for a given module. or am I misinterpreting the issue (catching up since I stood up for a sec)
15:44:41 <samccann> you have it right
15:44:56 <feyo[m]> yeah totally. yes/no 1/0 etc all still work obviously. but ansible-lint will throw an error and only accept true/false
15:44:59 <thedoubl3j> while I am very much pro consistency, what lint enforces might not be the "only" thing ansible and or the modules accept
15:45:03 <briantist> "best practices" is a loaded term imo, it's pretty much never objective, it's always from the POV of the persons or entitiy writing them
15:45:31 <thedoubl3j> that it is briantist I hate the term but understand its place some times
15:46:14 <thedoubl3j> people immediately look for "best way to write without errors" and there is always another path you can take
15:46:18 <briantist> yeah I hear you, more and more though I feel like its "place" is to end debate by declaring the "one true" way to do something
15:47:19 <feyo[m]> personally I simply go with (most things) ansible-lint recommends just to get consistency in the teams/projects I work.
15:47:42 <thedoubl3j> that it seems but I feel like that will be punching smoke. in OSS, someone from the woodwork will show up with something new
15:47:57 <feyo[m]> it just comes back to that. consistency. imagine having one person write yes/no and one person true/false inside the same project.
15:48:50 <feyo[m]> but, I feel like this is drifting off somewhat. sorry for that ^^
15:49:01 <thedoubl3j> yeah, I was just about to say the same thing feyo ⚡️ slight drift here
15:49:24 <samccann> heh that's okay. good discussion. Remember to add your thoughts to the issue as well
15:49:42 <samccann> #info Looking for ideas on how to get CI testing to work on rst pages excluded from ansible-core (what ansible/ansible CI covers today) - Please comment on https://github.com/ansible-community/community-topics/issues/111
15:49:43 <briantist> feyo[m]: I can imagine both yes/no and true/false being used in the same project, and that also being a good thing to do, precisely because they can each be clearer within the context of their use
15:50:17 <samccann> As a reminder - not all of our RST pages are currently going through CI tests in ansible/ansible. Something we need to remedy, but of course.. it's tricky.
15:52:27 <bcoca> it's tricky , should be the title of every PR/RFE from now on
15:52:41 <samccann> HAHAHA so very true
15:52:50 <samccann> okay we have less than ten minutes left so time for ...
15:52:58 <samccann> #topic Open Floor
15:53:12 <samccann> here's your chance to ask or bring up anything about docs. PRs, issues, other ideas etc?
15:53:38 <thedoubl3j> read through that issue, and yes. so many things to track
15:54:38 <samccann> heh yep
15:56:09 <samccann> ok if there's nothing else on anyone's mind, we can close out for today...
15:57:04 <samccann> #endmeeting