16:02:10 <samccann> #startmeeting Documentation Working Group aka DaWGs 16:02:10 <zodbot> Meeting started Tue Nov 29 16:02:10 2022 UTC. 16:02:10 <zodbot> This meeting is logged and archived in a public location. 16:02:10 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 16:02:10 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic. 16:02:10 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs' 16:02:11 <samccann> And welcome Zurich! 16:02:23 <felixfontein> o/ 16:02:29 <samccann> and I was blaming myself for that one Gwmngilfen 16:02:43 <oranod> James Joyce's grave is in Zurich. just a bit of interesting info for your day. 16:02:43 <samccann> oh that is interesting. TIL 16:02:55 <oranod> it's actually a nice place to visit 16:02:55 <samccann> @room Meeting time! Who is here to talk the docs? 16:02:56 <oranod> o/ 16:02:56 <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! 16:03:12 <felixfontein> oranod: hmm, interesting, never heard about that before :) 16:03:13 <samccann> To any newcomers - again, welcome. We chair all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info or #link (to add a link) 16:03:13 <samccann> #chair Don Naro 16:03:13 <zodbot> Current chairs: Don Naro samccann 16:03:25 <samccann> General run of the meeting - We go over action items, give docs updates.. maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!) 16:03:44 <samccann> #chair felixfontein 16:03:44 <zodbot> Current chairs: Don Naro felixfontein samccann 16:03:56 <samccann> briantist: around to talk docs today? 16:04:09 <oranod> felixfontein: https://www.tripadvisor.ie/Attraction_Review-g188113-d542816-Reviews-James_Joyce_s_Grave-Zurich.html 16:04:17 <felixfontein> he said he's travelling, but maybe he's around 16:04:28 <samccann> heh docs... and travel tips! 16:04:53 <oranod> I know all the good graveyards in Europe 16:05:01 <samccann> Official agenda is https://github.com/ansible/community/issues/643#issuecomment-1323986744 16:05:10 <samccann> oh fun! in a macabre sort of way 16:05:50 <samccann> felixfontein: did you want to go over your two antsibull-docs PRs that you added to the agenda this week? 16:06:00 <felixfontein> sure :) 16:06:08 <samccann> if the meetup allows :-) 16:06:13 <felixfontein> the first one is already merged since you approved it, so it's just one left ;) 16:06:28 <felixfontein> it was just doors opening at 17:00 (i.e. 6 minutes ago) 16:06:50 <felixfontein> #topic Improve environment variable handling 16:06:51 <felixfontein> #link https://github.com/ansible-community/antsibull-docs/pull/73 16:07:41 <felixfontein> this PR does two things: 1) it uses correct RST formatting (:envvar: role) for environment variables, 2) it adds an index of all environment variables (that are not defined in the core config) 16:08:11 <samccann> so I love it and that it's hotlinked! 16:08:22 <felixfontein> I started with 1) and then noticed that 2) is needed, since :envvar: is basically a reference to the corresponding `.. envvar::` directive 16:08:41 <felixfontein> oh, there was a third part: 3) allow to declare env variable fallbacks for module arguments 16:08:43 <samccann> but the colors aren't obvious that it's a hotlink to that index page entry. Is that a theme thing to ask that it be in blue or something so it's at least suggestive of a hotlink? 16:08:50 <felixfontein> but I can take that one out if it is too controversial 16:09:10 <felixfontein> the colors come from the theme / Sphinx itself, and that's already a problem for env variables in core itself 16:09:33 <felixfontein> see for example https://docs.ansible.com/ansible/latest/reference_appendices/config.html#action-warnings, there the env variables are also clickable 16:09:36 <samccann> ok I'll open a theme request on the ansible theme 16:10:09 <felixfontein> that part is very likely inherited from the RTD theme, but should be easy to adjust 16:10:58 <felixfontein> I think the index is nice, but I'm not sure where it should be placed. it cannot be added to the https://docs.ansible.com/ansible/latest/reference_appendices/config.html page since that's autogenerated by some completely different code (part of ansible-core) 16:11:10 <samccann> #action samccann open ansible theme request to change :envvar: output to blue so it is obvioius that it's a hotlink 16:12:04 <samccann> well if that config page is the right place, we can add it there in the code in ansible/ansible. 16:12:26 <felixfontein> what do you think of the markup and of the index (https://ansible.fontein.de/collections/environment_variables.html shows how it looks for some collections, I would expect the one for Ansible to be a lot larger) in general? 16:12:36 <samccann> or we could add it here https://docs.ansible.com/ansible/latest/installation_guide/intro_configuration.html#environmental-configuration 16:12:46 <felixfontein> oh right, we could add a RST include statement. that would be possible. 16:13:33 <samccann> So maybe the next step is to just open an issue in ansible/ansible for these two items? so we don't lose track 16:13:41 <felixfontein> so basically there would be two steps: 1) get the antsibull-docs PR merged and released, 2) bump the antsibull-docs version in core (devel) and update the script for the config page to link / include the new index 16:13:47 <felixfontein> sounds good! 16:13:54 <samccann> Also dunno what #3 was above or who would need to revew it 16:14:27 <samccann> are you up for opening the ansible/ansible docs issue felixfontein when you get a chance? 16:14:31 <felixfontein> another thing is allowing modules to declare the env variable fallbacks for options in the documentation 16:14:35 <felixfontein> BRB, wifi change 16:15:20 <felixfontein> re 16:15:23 * acozine belated joins in 16:15:34 <felixfontein> I was using my phone before, now I'm using the local wifi (just got credentials) :) 16:15:45 <felixfontein> #chair acozine 16:15:45 <zodbot> Current chairs: Don Naro acozine felixfontein samccann 16:16:13 <oranod> hey acozine 16:16:13 <samccann> welcome welcome 16:16:20 <felixfontein> about env variable fallbacks for options in the documentation: we should probably bring it up with core if we want to have it 16:16:51 <felixfontein> I already created a draft PR for ansible-core which supports it in validate-modules and ansible-doc (by adding version_added_collection and friends to it as well), but that likely won't trigger a discussion :) 16:17:11 <samccann> #action open ansible/ansible docs issue to add links to the new collection envvar index page after the next antsibull-docs release 16:17:38 <bcoca> felixfontein: we just discussed that a bit ... i still think its confusing to users, but ship sailed long ago with aws and networking ussing env vars (former directly, latter indirectly via fallbakc) 16:17:48 <felixfontein> I'm mainly afraid that documenting env variables for modules needs a similar approval chain as for semantic markup... 16:18:16 <bcoca> felixfontein: there was an approval chain for semantic markup? 16:18:23 <samccann> hhmmm... 16:18:30 <felixfontein> bcoca: ah, ok. I agree with the confusing part, especially since users not always understand where and how modules are executed and thus which env variables are available. 16:18:42 <samccann> bcoca yeah, and it failed (aka is just sitting in someone's queue somewhere, dying of neglect) 16:18:50 <felixfontein> bcoca: basically all docs consumer projects seem to have to approve JSON docs output changes... 16:19:15 <felixfontein> though I would hope that most consumers will simply ignore things they don't understand 16:19:15 <samccann> felixfontein: can you elaborate on how this would impact GalaxyNG docs display? 16:19:15 <bcoca> samccann: didnt know we even had a chain nor whom the links are ... 16:19:26 <samccann> ah okay so it's a json docs output change 16:19:33 <bcoca> felixfontein: right now everything needs everyone's approval/nonveto 16:19:41 * samccann cries river of tears 16:19:43 <felixfontein> samccann: it really depends on their code. if their code behaves like antsibull-docs and prints errors/warnings if unknown fields are found, they are affected. if they simply ignore it, they are fine. 16:19:55 <felixfontein> bcoca: which is horrible :) 16:19:56 <bcoca> samccann: you are main consumer of json docs output ... but also galaxy and lint now 16:19:59 <bcoca> and lsp .. 16:20:02 <samccann> bcoca: yeah, it's a busted chain for sure 16:20:04 <bcoca> and ... probably forgetting someone 16:20:20 <bcoca> felixfontein: welcome to my world ... i used to 'just do it' ... 16:20:29 <felixfontein> docsite / antsibull-docs and ansible-lint / vscode are easy to adjust (I know where their schemas live :D ) 16:20:35 <samccann> yeah. that's a river of tears kind thing. Can you back that out of this pr felixfontein ? 16:21:03 * bcoca walks away and schedules extra hour for crying in corner 16:21:16 <felixfontein> samccann: we could also allow it in antsibull-docs, to prevent errors printed there if someone use it, but not allow it in ansible-test validate-modules, which basically means that nobody will use it 16:21:24 <samccann> the gist of it is, we have no real way to approve changes to the JSON output so we are stuck with it stagnating 16:21:28 <felixfontein> bcoca: I feel with you! 16:21:42 <samccann> hahah yep 16:22:10 <felixfontein> I'll probably move it to a separate PR, so I can sneak it in ;) 16:22:38 <felixfontein> it would also be nice to document module option deprecations, or other stuff like mutually exclusive / required_if / ... 16:22:41 <samccann> yeah still sounds like a separate PR would be better 16:22:51 <samccann> heh 16:22:52 <samccann> actually thinking out loud 16:22:58 <felixfontein> (actually there was a PR for that 'recently' from the network team I think...) 16:23:04 <bcoca> felixfontein: have you seen my pr? 16:23:13 <felixfontein> bcoca: which one? you have multiple ones :) 16:23:17 <samccann> if you are changing just antsibull-docs right now, that has no impact anywhere else, right? 16:23:26 <samccann> it's only if you make a similar change in ansible/ansible that it has to be approved by everyone and their mother's uncle 16:23:27 <acozine> +1 for separate PRs, that makes each one easier to assess and (with luck) shepherd along 16:23:36 <bcoca> im down to 56! ... been good about that ... 16:23:59 <samccann> heh 16:24:01 <felixfontein> samccann: exatly, except that someone can start using by simply ignoring the ansible-test validate-modules errors... 16:24:10 <bcoca> https://github.com/bcoca/ansible/tree/controller_argspec trick question, it wqas branch 16:24:15 <felixfontein> bcoca: https://github.com/ansible/ansible/pulls/bcoca says 54 16:25:07 <bcoca> felixfontein: i have 2 against non ansible projects ... 16:25:27 <felixfontein> bcoca: ah, you were talking about all PRs you have, not just ansible/ansible ones :) 16:25:41 <bcoca> i'v set 60 as my limit 16:26:31 <felixfontein> I don't have a limit, but I think I try to have a lot less 16:26:37 <felixfontein> but then I also don't work fulltime on this :) 16:27:23 <bcoca> go back to docs, thsi is starting to sound like my therapy session ... 16:27:30 <felixfontein> :D 16:27:50 <felixfontein> ok, so to sum up, the general idea is good, we still have to figure out where exactly to place the index, and how to name that file 16:28:08 <felixfontein> I'll probably start with an experimental ansible/ansible PR that includes that file in the docsite 16:28:36 <felixfontein> if anyone has ideas / suggestions / improvement / other comments, please add them to the PR(s) :) 16:28:42 <samccann> cool thanks! 16:29:14 <felixfontein> thanks everyone :) 16:29:33 <felixfontein> I'll head off to the apero now, enjoying the meetup ;) 16:29:38 <samccann> Thanks felixfontein !! 16:29:39 <samccann> #topic Documentation updates 16:29:54 <felixfontein> #unchair felixfontein 16:29:54 <zodbot> Current chairs: Don Naro acozine samccann 16:29:57 <samccann> thanks! have fun! 16:29:57 <acozine> Enjoy felixfontein ! 16:30:01 <felixfontein> thanks! 16:30:55 <samccann> #info Ansible 7 released last week w/ docs! 16:30:57 <samccann> #info Archived 2.4 docs - redirects are live now. 16:30:57 <samccann> working on 2.5 now 16:31:08 <samccann> Do we have other general docs updates today? 16:31:27 * samccann hasn't fully recovered from eating too much pie last week 16:31:34 * acozine hasn't fully recovered from Covid 16:32:11 <samccann> ooch. yeah, that's a different sort of recovery! 16:32:37 <oranod> yikes. hope you get back to 100% soon acozine 16:33:29 <acozine> thanks, I am taking it slow, today is my first day back at the keyboard 16:35:05 <samccann> and you share it with us.. woot! 16:35:10 <acozine> sadly, it also means I don't have much to say 16:35:19 <samccann> me either this week. 16:35:22 <acozine> but i enjoy the camaraderie 16:35:32 <samccann> cups of 🍵for all! 16:35:41 <samccann> and a 🍪 16:36:36 <samccann> ok I've digressed quite a bit lol! 16:36:38 <acozine> heh 16:36:43 <samccann> #topic Open Floor 16:36:43 <acozine> are there any open PRs we should look at? 16:37:01 <acozine> oh, how did the release turn out in the end? 16:37:05 <samccann> since I've run out of steam today. anyone have docs thoughts to talk about? 16:37:37 <oranod> I guess we could mention the fact the docsite repo will be public later this week 16:38:03 <samccann> woo hoo!!! 16:38:07 <oranod> #info the plan is to make the ansible/docsite repo, which has the html fragements for docs.ansible.com, public 16:38:26 <acozine> ooh, that is great news! 16:38:43 <acozine> now we can have multiple sets of eyes on all those pesky redirects 16:38:48 <oranod> yes! 16:38:57 <oranod> the redirects as well as the layout and navigation 16:39:23 <oranod> I think it'll be great to tie into the personas that samccann is working on too (and will also bring to the community) 16:39:38 <samccann> yep for sure 16:39:50 <samccann> will be a funfilled few months in docs land! 16:40:33 <samccann> as for PRs to review - https://github.com/ansible/ansible/pull/79221 16:40:39 <samccann> mostly the comment on the proposed output 16:41:09 <samccann> https://github.com/ansible/ansible/pull/79221#issuecomment-1329363454 for a direct link 16:41:31 <samccann> The table is great but quite wide. So i tried shrinking 3 columns into 1 and would like feedback on whether it works or not 16:41:53 <samccann> this is the original table in the PR - https://github.com/ansible/ansible/pull/79221#issuecomment-1293939886 16:42:28 <oranod> ooof. are those footnote links in table cells? 16:44:18 <samccann> yes 16:44:30 <samccann> they show up below the table (tho not great, it's a theme problem) 16:45:38 <oranod> yeah... that's a pretty big accessibility no no 16:46:38 <oranod> I can take a look and offer an alternative but just wanted to point that out 16:47:04 <oranod> that one always stands out to me because I have a friend who uses a screen reader and absolutely hates those lol 16:47:50 <samccann> ah good to know! 16:48:44 <samccann> and I have the PR locally with the updated table so I can implement whatever you suggest for the footnotes. 16:49:55 <samccann> this new docs issue is a fun one - https://github.com/ansible/ansible/issues/79482 16:50:18 <samccann> edit on github disappeared from some pages after the user guide restructure 16:50:52 <oranod> oh no 16:50:52 <samccann> I haven't looked at the details yet to see why that might be. I know we have 'exceptions' in the code that controls this. My guess is some of these new pages hit one of those exceptions. but I could be out in space on that one 16:52:21 <acozine> hm, that's weird 16:53:50 <samccann> ok we have a few minutes left. any other topics? 16:56:12 <oranod> just thinking out loud here but I did a talk in Dublin last week that focused on docs, more specifically about being a content developer working on a devOps team. I wonder if there's a way to share that with the community here? 16:56:23 <oranod> might be something to get a docs convo going, etc 16:56:27 <samccann> by content developer, do you mean someone like felix... or a writer? 16:57:22 <oranod> in my mind a content developer is kind of writer + creating tools and stuff to make docs available 16:57:41 <oranod> so probably more like what felix is doing 16:58:15 <samccann> ok. We should talk to greg and see if there's a way to do a video here, then just pick a day/time and put it in the bullhorn 16:58:44 <samccann> but I like the idea of having a presentation (especially when I'm not presenting :-) 16:58:55 <oranod> yeah that sounds fine. it might not really even be worth it but just a thought. 16:59:01 <acozine> maybe next contrib summit? 16:59:12 <oranod> although I honestly hate the idea of recording myself on video 16:59:24 <samccann> well I'm thinking it would be nice to have it sooner/less formal etc 16:59:58 <oranod> perhaps then too acozine but I guess it isn't too specific to ansible at the same time 17:00:16 <acozine> ah, gotcha 17:00:29 <samccann> Ok we're about at time again 17:00:49 <samccann> #endmeeting