15:02:23 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:02:23 <zodbot> Meeting started Tue Jun 13 15:02:23 2023 UTC.
15:02:23 <zodbot> This meeting is logged and archived in a public location.
15:02:23 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:02:23 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:02:23 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:31 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:45 <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:02:59 <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)
15:03:00 <sutapa_bhattacha> o/
15:03:05 <sutapa_bhattacha> hello
15:03:07 <samccann> #chair sutapa_bhattacharjee
15:03:07 <zodbot> Current chairs: samccann sutapa_bhattacharjee
15:03:16 <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!)
15:03:27 <samccann> official agenda at https://github.com/ansible/community/issues/678#issuecomment-1579267173
15:03:42 <samccann> felixfontein: briantist - around to talk docs today?
15:04:12 <samccann> acozine waves but can't make it today... she's bringing all her hands to ... some all hands thing :-)
15:04:44 <TVo[m]> Hello o/
15:04:56 <samccann> #chair TVo
15:04:56 <zodbot> Current chairs: TVo samccann sutapa_bhattacharjee
15:05:00 <samccann> welcome welcome!
15:05:13 <samccann> #topic Action Items
15:05:23 <samccann> #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 <samccann> #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 <samccann> 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 <briantist> I'm around a little
15:07:34 <samccann> #chair briantist
15:07:34 <zodbot> Current chairs: TVo briantist samccann sutapa_bhattacharjee
15:07:39 <samccann> cool
15:07:41 <samccann> we'll take a little :-)
15:08:00 <samccann> unfortunately we seem a small crew today to discuss a major issue, but such as it is
15:08:14 <TVo[m]> sorry if I'm slow to respond. I'm on another community call
15:08:19 <samccann> no worries
15:08:25 <samccann> #topic Moving docs out of ansible/ansible
15:08:39 <samccann> #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 <samccann> #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 <samccann> 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 <samccann> 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 <samccann> This is just the first step in that path so to speak.
15:10:51 <samccann> #info starting this Thursday, we'll test out the new ansible/ansible-documentation repo and publish devel docs from there.
15:11:12 <samccann> #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 <briantist> 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 <TVo[m]> I've tried to follow the specifics on this effort, too... I got stuck on "packaged docs"  - what exactly are those?
15:12:34 <felixfontein> o/
15:12:40 <felixfontein> sorry, was doing something else and forgot about the time...
15:12:49 <samccann> #chair felixfontein
15:12:49 <zodbot> Current chairs: TVo briantist felixfontein samccann sutapa_bhattacharjee
15:13:20 <samccann> 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 <samccann> welcome felixfontein
15:14:08 <samccann> 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 <oranod> o/
15:14:33 <samccann> #chair Don Naro
15:14:33 <zodbot> Current chairs: Don Naro TVo briantist felixfontein samccann sutapa_bhattacharjee
15:14:42 <samccann> haha like beteljuice... say his name and he shows up!
15:14:44 <briantist> and the tractor is stuck behind a donkey, and the donkey has laryngitis,
15:14:47 <felixfontein> sounds like fun :)
15:15:01 <oranod> 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 <samccann> heehee
15:15:26 <oranod> I'd pay to hear a donkey with laryngitis tbh
15:15:47 <oranod> not that I'd wish anything bad on an animal
15:16:22 <briantist> the donkey, having lost its voice, would also pay to be heard
15:16:37 <samccann> are there any points you want to bring up about the docs moving out of ansible/ansible Don Naro ?
15:17:18 <oranod> 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 <samccann> felixfontein: is there anything you're doing that depends on the docs being in ansible/ansible vs some other repo?
15:18:34 <felixfontein> 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 <felixfontein> 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 <felixfontein> or is it mainly the *build process* and some version-independent documentation that is in the other repo?
15:19:53 <samccann> the core feature would need a matching docs PR in the other repo, yes
15:20:01 <samccann> the core team has committed to doing this.
15:20:26 <felixfontein> ok, so basically the only docs left in ansible/ansible will be the module/plugin docs?
15:20:31 <samccann> 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 <felixfontein> (basically the ansible.builtin collection docs)
15:20:58 <samccann> 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 <felixfontein> sounds good to me, then
15:22:20 <samccann> do we know of anyone else specifically we should run this by who isn't here today?
15:23:09 <felixfontein> 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 <felixfontein> 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 <samccann> 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 <briantist> 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 <briantist> decoupling sounds like a good move though
15:27:08 <samccann> 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 <samccann> 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 <felixfontein> I meant more like anwesha_ and rooftopcellist, but #ansible-packaging is also a good idea :)
15:28:44 <felixfontein> actually a very good one, since some of them also build and package the docs
15:29:06 <samccann> yeah was remembering that when I posted there... might get interesting feedback
15:29:16 <felixfontein> indeed
15:30:17 <samccann> ok moving on
15:30:27 <samccann> #topic Documentation updates
15:30:39 <samccann> #info removing local copies of interphinx links - https://github.com/ansible/ansible/pull/80994
15:31:07 <samccann> 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 <samccann> 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 <felixfontein> the only reason I can think of are offline builds
15:33:14 <samccann> 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 <samccann> 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 <felixfontein> 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 <samccann> https://github.com/ansible/ansible/pull/80994#issuecomment-1589265337
15:35:57 <felixfontein> 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 <samccann> 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 <felixfontein> removing them also makes the final checkout smaller, so IMO removing them is still a good idea
15:38:16 <samccann> ok well once Imove the PR, I'll ask for community review/approval
15:38:27 <samccann> our repo, our bloat :-)
15:38:35 * samccann needs that on a mug or a t-shirt
15:39:08 <samccann> #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 <samccann> 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 <oranod> imo that's not really a How To guide, more of a quickstart tutorial
15:40:09 <samccann> to explain - this how to for EEs will talk about builder, navigator, and likely over time - examples in AWX etc
15:40:33 <samccann> so that's a separate but also interesting discussion -
15:40:37 <felixfontein> I guess it belongs in the 'unversioned' part of the docsite
15:40:50 <samccann> should a quickstart tutorial include  multiple projects?
15:41:10 <oranod> in the case of something like builder, probably
15:41:17 <samccann> Don Naro: maybe you can explain your  thoughts here wrt adding this to the existing ansible getting started guide
15:41:18 <felixfontein> 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 <samccann> walking through the specifics might help
15:41:55 <oranod> I'll try to give a brief overview because I could talk at length about it
15:42:09 <oranod> once again there are multiple threads
15:42:25 <samccann> #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 <felixfontein> I guess the best answer is "it's complicated". which answers 99% of all non-trivial questions ;)
15:44:38 <oranod> 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 <oranod> 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 <samccann> ok so the immediate question - should the EE overview and quickstart move into the Ansible getting started guide?
15:45:42 <oranod> there's also the move to make Getting Started more "project focused"
15:45:59 <oranod> hang on and I'll grab a link. jklech is working away on it.
15:46:00 <samccann> https://github.com/ansible/community-docs/pull/60 is the content we're talking about
15:46:17 <samccann> yeah see this is where I get into a fundamental problem
15:46:20 <oranod> here is the issue: https://github.com/ansible/ansible/issues/80941
15:46:36 <samccann> to me right now, Ansible getting started is... getting started with the Ansible package (or core, it probably works for both)
15:46:52 <samccann> once we start adding more projects to it, it's not focused on the package docs.
15:47:14 <samccann> Maybe that's the right direction -  turn the Ansible package docs into more ecosystem-like docs.
15:47:40 <oranod> I don't think we want to do too much of that. it's a balance.
15:47:54 <oranod> but we probably don't want to have too many different places to go to for Getting Started
15:48:26 <oranod> and the changes from issue 80941 should result in something that could very nicely lead into what Andrei is working on
15:49:44 <oranod> 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 <samccann> felixfontein: briantist .. any initial thoughts? I know it's hard to envision before a PR is ready
15:52:09 <briantist> it really is complicated... as oranod said it's all about balance
15:52:15 <briantist> the ansible ecosystem is large
15:52:29 <samccann> 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 <briantist> too much or too little all in one place leads to bad experiences for different reasons...
15:52:49 <samccann> Thanks briantist  good points
15:53:17 <oranod> samccann: that sounds familiar but I'm not going to be able to dig it up in a timely manner
15:53:34 <felixfontein> I agree with briantist...
15:54:13 <samccann> ok so my feeling is, we may get pushback for adding it to the existing getting started
15:54:17 <briantist> I wish I had more actionable advice for how to achieve that balance, not my strong suit heh
15:54:40 <samccann> but that doesn't mean we can't add an additional guide that is 'integrating other projects with your ansible work'
15:54:42 <felixfontein> (I also know why I prefer working on docs tools than on docs itself :) )
15:54:53 <samccann> or you know.. something with a much catchier  title
15:54:56 <bcoca> felixfontein: idem!
15:55:05 <bcoca> ansible: getting started
15:55:15 <bcoca> ansible: enteprise starting guide
15:55:28 <bcoca> ansible: beware all ye who enter ...
15:55:32 <samccann> Ansible ecosystem getting started :-)
15:55:51 <bcoca> ansible: expanding into galaxy
15:55:57 <oranod> lol
15:55:57 <briantist> ansible: here be dragons, there be dragons, everywhere be dragons,
15:56:08 <bcoca> briantist++
15:56:16 <samccann> 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 <oranod> ansible: an ecosystem of dragons
15:56:26 <samccann> oof!
15:56:30 <samccann> #topic Open Floort
15:56:34 <samccann> AAAHAHA
15:56:36 <bcoca> ansbile; galaxy and space dragons
15:56:37 <samccann> gonna leave that type
15:56:39 <samccann> typo
15:56:54 <samccann> anyway, we have a few minutes... other than space dragons, any other topic to bring up?
15:57:16 <samccann> felixfontein: did you want more eyes on that `env` semantic markup issue?
15:57:19 <felixfontein> well, there's https://github.com/ansible-community/antsibull-docs/issues/164 :)
15:57:22 <bcoca> dragon knights (riding the space dragons)
15:57:41 <felixfontein> I'm probably going for idea 1 (https://github.com/ansible-community/antsibull-docs/issues/164#issuecomment-1586181733)
15:57:48 <felixfontein> and try this out in a PR
15:58:05 <bcoca> current ansible-doc CAN expose all env vars from plugins also
15:58:11 <felixfontein> 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 <samccann> #info looking for feedback on how to handle enviroment variables - https://github.com/ansible-community/antsibull-docs/issues/164
15:58:31 <felixfontein> bcoca: I mean the ones mentioned in free text, like `You can also use E(FOOBAR) to configure ...`
15:58:34 <bcoca> 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 <samccann> :ansenvvar: sounds good
15:59:15 <bcoca> or add a reff plugin to :envvar: , defaulting to config page otherwise
15:59:59 <felixfontein> bcoca: there are many env vars mentioned in module docs that don't show up in any non-module plugin
16:00:00 <bcoca> ^ 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 <bcoca> felixfontein: that is why the default should be the config page
16:00:33 <felixfontein> the config page is mostly wrong for these though
16:00:35 <bcoca> by plugin i also meant module itself
16:00:49 <bcoca> if what you are reffering to is 'fallback env vars'
16:01:01 * bcoca needs some napalm to remove fallback_caller
16:01:07 <felixfontein> for example why should `ALICLOUD_ACCESS_KEY` point to the ansible config page?
16:01:13 <felixfontein> (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 <bcoca> should point to the option that does same in module
16:01:36 <bcoca> again, modules ARE plugins in this context
16:01:56 <bcoca> they just dont have 'env' section (which i would add and remove the whole fallback system)
16:02:11 <felixfontein> 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 <bcoca> with note (marquee and blink tags) that specifies those env vars are ON THE TARET
16:02:39 <bcoca> felixfontein: used by the underlying libarary, but should in the end still map to module option
16:02:55 <felixfontein> Like `Setting this option to 'true' will set the FOOBAR env variable for the program this module calls`
16:04:07 <felixfontein> anyway, I'm going to try this out, and I'll provide some links to results
16:04:13 <oranod> got to run but nice to see you all. thanks!
16:04:21 <samccann> ok cool thanks felixfontein
16:04:31 <samccann> looks like were at an end... thanks everyone!
16:04:35 <samccann> #endmeeting