15:01:05 #startmeeting Documentation Working Group aka DaWGs 15:01:05 Meeting started Tue Jun 28 15:01:05 2022 UTC. 15:01:05 This meeting is logged and archived in a public location. 15:01:05 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 15:01:05 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:01:05 The meeting name has been set to 'documentation_working_group_aka_dawgs' 15:01:14 it's time to light the lights? 15:01:23 #topic opening chatter 15:01:28 * acozine hums the Muppets theme quietly 15:01:30 this is it, we'll hit the heights 15:01:38 heh 15:01:47 @room Meeting time! Who is here to talk the docs? 15:01:49 o/ 15:01:56 o/ 15:01:57 Not around for today's meeting. I'll skim scroll back later on 15:02:07 #chair Don Naro acozine 15:02:07 Current chairs: Don Naro acozine samccann 15:02:08 gundalow: we'll miss you! 15:02:14 kinda here, pretty distracted unfortunately 15:02:31 #chair briantist 15:02:31 Current chairs: Don Naro acozine briantist samccann 15:02:32 I'm here with the caveat that I'll need to drop off at half past but will catch up later 15:02:50 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 felixfontein: you around today? 15:03:01 Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1161936659 15:03:53 #topic Documentation updates 15:04:29 o/ just here to lurk 15:04:47 #chair feyo ⚡️ welcome! 15:04:47 Current chairs: Don Naro acozine briantist feyo samccann welcome! ⚡️ 15:04:53 everyone gets a chair ;-) 15:05:22 So let's start with: 15:05:23 #info Userguide getting a facelift! https://github.com/ansible/ansible/issues/78082#issuecomment-1159185553 15:05:42 That has the details, but you can see the start of it at https://docs.ansible.com/ansible/devel/index.html 15:05:54 lurking is more comfortable with a chair! 15:05:57 This is Don Naro 's party! (aka he's doing all the work) 15:06:53 o/ also lurking, since there are so many cool people here 15:07:16 #chair cybette welcome welcome 15:07:16 Current chairs: Don Naro acozine briantist cybette feyo samccann welcome welcome! ⚡️ 15:08:21 do you have a link to the PR? 15:08:32 this looks like great stuff! 15:08:44 There are multiple. let me check as I think most have been merged on this first file shuffle 15:08:54 https://github.com/ansible/ansible/pull/78097 15:09:01 https://github.com/ansible/ansible/pull/78099 15:09:08 https://github.com/ansible/ansible/pull/78103 15:09:45 those are the three I've got so far. I would like to tackle the playbooks topics next. 15:10:32 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 although I'm sure samccann will graciously correct me in the PR queue 15:11:20 heh well when it comes to the deeper stuff, we may need more reviewers. 15:11:45 But this is all just staying in devel until ansible-2.14 releases so we have time to make adjustments etc 15:12:16 great stuff Don Naro and samccann ! 15:12:37 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 Don Naro: Sure we could! At what point? Before or after you separate out things like playbooks and inventory etc? 15:14:20 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 acozine: true 15:15:19 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 o/ 15:15:33 apologies for the tardiness 15:15:56 #chair thedoubl3j welcome welcome! 15:15:56 Current chairs: Don Naro acozine briantist cybette feyo samccann thedoubl3j welcome welcome! ⚡️ 15:16:22 anything else on the userguide revamp before we shuffle on? 15:17:21 I'll take a look at the PRs, this week or next 15:18:05 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 meanwhile... 15:18:48 #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 ^^ 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 and one more plug for help: 15:19:52 #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 ;-) 15:20:26 We are doing well on chiseling away at that backlog! 15:20:39 W00t! 15:20:45 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 lol thanks for the help! 15:21:12 wanted to get the low hanging fruit to entice them in 15:21:23 easyfix hoarding! 15:21:28 AHAHAHAH 15:21:44 gotta get those contrib numbers somehow right?? xD 15:22:12 tell them badges are here (or coming) - so extra fun when they contribute 15:22:55 any stickers going? I'm pretty easy to motivate if you offer me stickers. 15:23:21 lol! We used to have DaWGs stickers. dunno if we have any left acozine ?? 15:23:42 I have one ;) still need to find the right spot for it. 15:23:45 erm, I'm sure they're here somewhere 15:23:53 those are high valued stickers. 15:24:06 my laptop has mine, but it will need to be replaced soon, so... gonna try peeling it off! 15:24:09 but since we moved, "somewhere" got a little less well-defined 15:24:14 hehe 15:24:34 We are finishing that process now acozine and I concur big time with that. 15:24:46 ok onto the next topic... 15:24:47 #topic doctools 15:24:56 #info - Need reviews for canonical URL in Ansible 2.3 https://github.com/ansible/ansible/pull/78135 15:25:29 I might have a couple of DaWGs stickers, and can print more if needed! 15:25:38 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 wow, congratulations on publishing 2.3 15:26:03 cybette: cool! Somewhere I have the original artwork I can pass on. Might be time for a reprint! 15:26:54 We still havea goal to create a docs archive site and move all the old docs over to that. 15:27:43 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 thanks Don Naro ! 15:28:00 thanks Don Naro 15:28:14 #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 This came up yesterday and thanks to feyo ⚡️ for summarizing it all in that issue 15:28:44 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 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 I believe the current code overrides ANY boolean options with `yes/no` in the published docs on docs.ansible.com 15:30:01 only in the generated stuff. It doesn't change examples or text afaik 15:30:17 so the underlying docstrings may contain any legal boolean (yes/no, 1/0, true/false, etc.) 15:30:21 yeah, exactly 15:30:27 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 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 Then the coders can battle it out :-) 15:32:43 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 and that is annoying and frustrating and feels just plain wrong 15:33:28 when you add in the fact that other ways of parsing those docstrings give you different results 15:33:32 well, it's a mess 15:33:36 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 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 i understand its technically not wrong either way, but its a strange thing to have 15:34:23 when we chose the current path, I think there were 2 arguments that kinda led the discussion: 15:34:49 one was, if we have to confuse some group of people, it's better to confuse new users than developers 15:35:26 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 but now we DO control ansible-lint (sort of, at least) and we're still confusing people 15:36:30 we also had a very active community member at that time who had very strong views and a very loud voice 15:36:31 probably confusing more after the repo move :P 15:36:38 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 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 feyo ⚡️: yes, and I think it's probably time to try a different approach 15:37:29 but a little history helps us all understand how we got to where we are 15:37:36 and maybe why change could be a good thing 15:37:49 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 ansible.. RAW AND UNCUT! heh 15:38:29 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 well if you have other thoughts/notions etc please add them to the issue 15:38:35 and that yaml1.2 enforces true/false 15:38:41 how true is that? 15:38:52 heh, it's at least truthy 15:38:53 That alas we don't know here personally. 15:39:34 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 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 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 at least it wouldnt seem like the docs say "yes/no is correct" and ansible-lint saying a different thing 15:41:38 in general I think being consistent over the different official ansible projects would be better for new users as well 15:42:00 but as was mentioned before, that is a rather larger discussion 15:42:24 yeah, wider consistency would be wonderful, though the docs team can only change the docs output 15:42:38 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 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 you have it right 15:44:56 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 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 "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 that it is briantist I hate the term but understand its place some times 15:46:14 people immediately look for "best way to write without errors" and there is always another path you can take 15:46:18 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 personally I simply go with (most things) ansible-lint recommends just to get consistency in the teams/projects I work. 15:47:42 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 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 but, I feel like this is drifting off somewhat. sorry for that ^^ 15:49:01 yeah, I was just about to say the same thing feyo ⚡️ slight drift here 15:49:24 heh that's okay. good discussion. Remember to add your thoughts to the issue as well 15:49:42 #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 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 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 it's tricky , should be the title of every PR/RFE from now on 15:52:41 HAHAHA so very true 15:52:50 okay we have less than ten minutes left so time for ... 15:52:58 #topic Open Floor 15:53:12 here's your chance to ask or bring up anything about docs. PRs, issues, other ideas etc? 15:53:38 read through that issue, and yes. so many things to track 15:54:38 heh yep 15:56:09 ok if there's nothing else on anyone's mind, we can close out for today... 15:57:04 #endmeeting