15:02:23 #startmeeting Documentation Working Group aka DaWGs 15:02:23 Meeting started Tue Jun 13 15:02:23 2023 UTC. 15:02:23 This meeting is logged and archived in a public location. 15:02:23 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 15:02:23 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:02:23 The meeting name has been set to 'documentation_working_group_aka_dawgs' 15:02:31 @room Meeting time! Who is here to talk the docs? 15:02:45 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:02:59 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) 15:03:00 o/ 15:03:05 hello 15:03:07 #chair sutapa_bhattacharjee 15:03:07 Current chairs: samccann sutapa_bhattacharjee 15:03:16 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!) 15:03:27 official agenda at https://github.com/ansible/community/issues/678#issuecomment-1579267173 15:03:42 felixfontein: briantist - around to talk docs today? 15:04:12 acozine waves but can't make it today... she's bringing all her hands to ... some all hands thing :-) 15:04:44 Hello o/ 15:04:56 #chair TVo 15:04:56 Current chairs: TVo samccann sutapa_bhattacharjee 15:05:00 welcome welcome! 15:05:13 #topic Action Items 15:05:23 #info closed samccann to inform community-writers about EE epic for a place to help out editorially and with info architecture etc 15:05:34 #info closed issue in community-topic for requesting cheatsheet help and on reddit as well - https://github.com/ansible-community/community-topics/issues/232 15:06:32 sadly, we've mostly gotten crickets on that one. I think we may have to resort to making it up ourselves (cheatsheet items) and seeing who comments at the PR level 15:07:20 I'm around a little 15:07:34 #chair briantist 15:07:34 Current chairs: TVo briantist samccann sutapa_bhattacharjee 15:07:39 cool 15:07:41 we'll take a little :-) 15:08:00 unfortunately we seem a small crew today to discuss a major issue, but such as it is 15:08:14 sorry if I'm slow to respond. I'm on another community call 15:08:19 no worries 15:08:25 #topic Moving docs out of ansible/ansible 15:08:39 #info this is part of putting package docs under ansible steering committee/community control. See https://github.com/ansible-community/community-topics/issues/243 15:08:50 #info an interim step is to move all docs out to ansible/ansible-documentation. From there, we can iterate faster to get to the point where the community package docs are under community control (likely another repo in ansible-community org) and separate from core docs. 15:09:38 So gist of it is - we put a bunch of docs in ansible/ansible that no longer relate specifically to core. It's been causing problems along the way, and seems now there are a number of folks behind the idea of removing all docs from ansible/ansible and putting them in a separate docs repo 15:10:13 From there, we can experiment on splitting core docs out from package docs and putting package docs entirely in community hands (aka managing the docs, the backports, the publishing etc). 15:10:21 This is just the first step in that path so to speak. 15:10:51 #info starting this Thursday, we'll test out the new ansible/ansible-documentation repo and publish devel docs from there. 15:11:12 #info this also means docs PRs in ansible/ansible in the next two weeks will be asked to move over to ansible/ansible-documentation 15:11:27 I've been seeing the notifications for that, haven't had a chance to really read through the issues/comments, but the gist sounds good to me 15:12:13 I've tried to follow the specifics on this effort, too... I got stuck on "packaged docs" - what exactly are those? 15:12:34 o/ 15:12:40 sorry, was doing something else and forgot about the time... 15:12:49 #chair felixfontein 15:12:49 Current chairs: TVo briantist felixfontein samccann sutapa_bhattacharjee 15:13:20 TVo: package docs is my shorthand way of referring to Ansible 8 for example, as something different/seprate from ansible-core 2.15 15:13:38 welcome felixfontein 15:14:08 unfortunately Don Naro is stuck behind a tractor and a train so will be late today... life's tough when you live in the sticks :-) 15:14:20 o/ 15:14:33 #chair Don Naro 15:14:33 Current chairs: Don Naro TVo briantist felixfontein samccann sutapa_bhattacharjee 15:14:42 haha like beteljuice... say his name and he shows up! 15:14:44 and the tractor is stuck behind a donkey, and the donkey has laryngitis, 15:14:47 sounds like fun :) 15:15:01 it's not quite the sticks. just how the wheel of fortune turns when I'm trying to get home for a meeting. 15:15:20 heehee 15:15:26 I'd pay to hear a donkey with laryngitis tbh 15:15:47 not that I'd wish anything bad on an animal 15:16:22 the donkey, having lost its voice, would also pay to be heard 15:16:37 are there any points you want to bring up about the docs moving out of ansible/ansible Don Naro ? 15:17:18 only that I'd like to make sure it doesn't break anything for felixfontein or anything going on in the community 15:18:18 felixfontein: is there anything you're doing that depends on the docs being in ansible/ansible vs some other repo? 15:18:34 I'm curious what will happen with all the ansible-core version specific docs, do they also move to the other repo? 15:18:47 so if a new feature is added to ansible-core, does it needs an accompanying PR in the other repo to add documentation for it? 15:19:08 or is it mainly the *build process* and some version-independent documentation that is in the other repo? 15:19:53 the core feature would need a matching docs PR in the other repo, yes 15:20:01 the core team has committed to doing this. 15:20:26 ok, so basically the only docs left in ansible/ansible will be the module/plugin docs? 15:20:31 as well as maintain 'technical stewarship' over the docs issues and PRs in that new repo. Meaning they will keep an eye, help review PRs etc 15:20:37 (basically the ansible.builtin collection docs) 15:20:58 yeah just the autogenerated stuff. that and the cli pages and a few others that are generated from the code by 'some magic' 15:21:23 sounds good to me, then 15:22:20 do we know of anyone else specifically we should run this by who isn't here today? 15:23:09 hmm, I think the most important folks are a) the core team, b) samccann and oranod, c) briantist and me... right now I cannot remember anyone else really being involved in these docs (any more) 15:23:39 informing the ansible community package release managers would make sense, since they need to know where they have to create their PRs :) 15:23:42 ok so briantist - would love for you to take a deeper look at the community topic(s) when you get a chance 15:24:37 I think I'm at the bottom of that list 😅 my small thing mostly depends on the projects that Felix maintains, but I will try to take a look as soon as I can 15:24:58 decoupling sounds like a good move though 15:27:08 ok I poked the ansible packaging room to let them know what's going on. Not sure who besides anwesha is doing community package releases 15:27:52 anything else on this topic we should talk about today? I'll ask that it be brought up tomorrow as well in the community WG as that has a wider audience for sure 15:28:27 I meant more like anwesha_ and rooftopcellist, but #ansible-packaging is also a good idea :) 15:28:44 actually a very good one, since some of them also build and package the docs 15:29:06 yeah was remembering that when I posted there... might get interesting feedback 15:29:16 indeed 15:30:17 ok moving on 15:30:27 #topic Documentation updates 15:30:39 #info removing local copies of interphinx links - https://github.com/ansible/ansible/pull/80994 15:31:07 so the local copies are huge and for Ansible 8 - broke ansible/ansible CI for a time (for every PR) 15:31:17 * samccann wonders why core wants docs out...:-P 15:31:57 so the first question - does anyone know/remember a reason for keeping local copies? It seems sphinx publishes these files to each docsite so the builds don't need them locally. 15:32:41 the only reason I can think of are offline builds 15:33:14 yeah I can't recall if it was sivel or matt but someone tested an offline docs build and said it doesn't work anymore anyway... but I could be mistaken 15:34:43 so one comment at the end of that PR mentions maybe it's not worth removing a large file from git because it makes the repo that much bigger anyway? 15:34:50 it does work offline, but you need some tricks ;) basically you need an antsibull collections cache with all collections needed in there. I'm not sure whether the git clone of the ansible-core repo is still there, if it is that one also needs internet 15:35:37 https://github.com/ansible/ansible/pull/80994#issuecomment-1589265337 15:35:57 I'm not sure how much removing will increase the size. my guess just by a tiny amount (for internal git housekeeping). 15:36:12 it makes me wonder if we should just leave the old ones there to 'rot' so to speak? It's the second time someone has mentioned the issue of git bloat so dunno what the correct step is 15:37:52 removing them also makes the final checkout smaller, so IMO removing them is still a good idea 15:38:16 ok well once Imove the PR, I'll ask for community review/approval 15:38:27 our repo, our bloat :-) 15:38:35 * samccann needs that on a mug or a t-shirt 15:39:08 #info considering how to handle how-to guides that include more than one project. See the EE issues for an example - https://github.com/ansible-community/community-team/issues/243#issuecomment-1588912447 15:39:43 that one is interesting as we debate where to put a how-to guide for EEs.. how much do we add to ansible package docs, do we need a new home for cross-project docs, etc etc 15:40:04 imo that's not really a How To guide, more of a quickstart tutorial 15:40:09 to explain - this how to for EEs will talk about builder, navigator, and likely over time - examples in AWX etc 15:40:33 so that's a separate but also interesting discussion - 15:40:37 I guess it belongs in the 'unversioned' part of the docsite 15:40:50 should a quickstart tutorial include multiple projects? 15:41:10 in the case of something like builder, probably 15:41:17 Don Naro: maybe you can explain your thoughts here wrt adding this to the existing ansible getting started guide 15:41:18 only when needed, but in this case I think it is needed - just building an EE without using it is a bit pointless 15:41:24 walking through the specifics might help 15:41:55 I'll try to give a brief overview because I could talk at length about it 15:42:09 once again there are multiple threads 15:42:25 #info should a quickstart tutorial include more than one project? General agreement is EEs do need to talk about more than one project. Just building an EE is useless w/o showing how to use the end result for example 15:42:43 I guess the best answer is "it's complicated". which answers 99% of all non-trivial questions ;) 15:44:38 actually all my thoughts are kind of summed up in the comments on that issue you've linked to samccann but I feel like we don't yet have the right home for the How To docs that would provide an opinionated end-to-end that helps people put existing skills to use 15:45:04 tutorials are more for learning new skills quickly, which is what I think Andrei has done a great job with in his testing and building ee's doc 15:45:22 ok so the immediate question - should the EE overview and quickstart move into the Ansible getting started guide? 15:45:42 there's also the move to make Getting Started more "project focused" 15:45:59 hang on and I'll grab a link. jklech is working away on it. 15:46:00 https://github.com/ansible/community-docs/pull/60 is the content we're talking about 15:46:17 yeah see this is where I get into a fundamental problem 15:46:20 here is the issue: https://github.com/ansible/ansible/issues/80941 15:46:36 to me right now, Ansible getting started is... getting started with the Ansible package (or core, it probably works for both) 15:46:52 once we start adding more projects to it, it's not focused on the package docs. 15:47:14 Maybe that's the right direction - turn the Ansible package docs into more ecosystem-like docs. 15:47:40 I don't think we want to do too much of that. it's a balance. 15:47:54 but we probably don't want to have too many different places to go to for Getting Started 15:48:26 and the changes from issue 80941 should result in something that could very nicely lead into what Andrei is working on 15:49:44 so it seems like a better, more natural fit that putting Andrei's doc into builder (which would likely result in some raised eyebrows from that team) or trying to shoehorn it into a How To section prematurely 15:50:43 felixfontein: briantist .. any initial thoughts? I know it's hard to envision before a PR is ready 15:52:09 it really is complicated... as oranod said it's all about balance 15:52:15 the ansible ecosystem is large 15:52:29 Don Naro: was there a comment somewhere that didn't like the idea of extending the getting started? I can't recall if it was talking about ansible-lint or something else. Maybe I just dreamt it lol 15:52:39 too much or too little all in one place leads to bad experiences for different reasons... 15:52:49 Thanks briantist good points 15:53:17 samccann: that sounds familiar but I'm not going to be able to dig it up in a timely manner 15:53:34 I agree with briantist... 15:54:13 ok so my feeling is, we may get pushback for adding it to the existing getting started 15:54:17 I wish I had more actionable advice for how to achieve that balance, not my strong suit heh 15:54:40 but that doesn't mean we can't add an additional guide that is 'integrating other projects with your ansible work' 15:54:42 (I also know why I prefer working on docs tools than on docs itself :) ) 15:54:53 or you know.. something with a much catchier title 15:54:56 felixfontein: idem! 15:55:05 ansible: getting started 15:55:15 ansible: enteprise starting guide 15:55:28 ansible: beware all ye who enter ... 15:55:32 Ansible ecosystem getting started :-) 15:55:51 ansible: expanding into galaxy 15:55:57 lol 15:55:57 ansible: here be dragons, there be dragons, everywhere be dragons, 15:56:08 briantist++ 15:56:16 ugh.. still have to look at that ancient galaxy guide in ansible/ansible and .. hopefully just nix it when galaxyNG comes out 15:56:20 ansible: an ecosystem of dragons 15:56:26 oof! 15:56:30 #topic Open Floort 15:56:34 AAAHAHA 15:56:36 ansbile; galaxy and space dragons 15:56:37 gonna leave that type 15:56:39 typo 15:56:54 anyway, we have a few minutes... other than space dragons, any other topic to bring up? 15:57:16 felixfontein: did you want more eyes on that `env` semantic markup issue? 15:57:19 well, there's https://github.com/ansible-community/antsibull-docs/issues/164 :) 15:57:22 dragon knights (riding the space dragons) 15:57:41 I'm probably going for idea 1 (https://github.com/ansible-community/antsibull-docs/issues/164#issuecomment-1586181733) 15:57:48 and try this out in a PR 15:58:05 current ansible-doc CAN expose all env vars from plugins also 15:58:11 if anyone has a good name for the role (even though it's mostly internal), feel free to chime in ;) maybe :ansenvvar: for now 15:58:17 #info looking for feedback on how to handle enviroment variables - https://github.com/ansible-community/antsibull-docs/issues/164 15:58:31 bcoca: I mean the ones mentioned in free text, like `You can also use E(FOOBAR) to configure ...` 15:58:34 but probably want to ref the plugin's page itself instread off a 'env var list page' (which i think we should kill in the end and just point to base config page) 15:58:38 :ansenvvar: sounds good 15:59:15 or add a reff plugin to :envvar: , defaulting to config page otherwise 15:59:59 bcoca: there are many env vars mentioned in module docs that don't show up in any non-module plugin 16:00:00 ^ though that might require adding evnvar as anchor also to config entry .. or we just keep current env var page (which i find confusing) 16:00:15 felixfontein: that is why the default should be the config page 16:00:33 the config page is mostly wrong for these though 16:00:35 by plugin i also meant module itself 16:00:49 if what you are reffering to is 'fallback env vars' 16:01:01 * bcoca needs some napalm to remove fallback_caller 16:01:07 for example why should `ALICLOUD_ACCESS_KEY` point to the ansible config page? 16:01:13 (found here: https://docs.ansible.com/ansible/devel/collections/community/general/ali_instance_module.html#ansible-collections-community-general-ali-instance-module) 16:01:27 should point to the option that does same in module 16:01:36 again, modules ARE plugins in this context 16:01:56 they just dont have 'env' section (which i would add and remove the whole fallback system) 16:02:11 bcoca: they aren't necessarily env vars used with env_fallback even, could be random other things they "just mention" in some documentation 16:02:18 with note (marquee and blink tags) that specifies those env vars are ON THE TARET 16:02:39 felixfontein: used by the underlying libarary, but should in the end still map to module option 16:02:55 Like `Setting this option to 'true' will set the FOOBAR env variable for the program this module calls` 16:04:07 anyway, I'm going to try this out, and I'll provide some links to results 16:04:13 got to run but nice to see you all. thanks! 16:04:21 ok cool thanks felixfontein 16:04:31 looks like were at an end... thanks everyone! 16:04:35 #endmeeting