15:30:35 <samccann> #startmeeting Documentation Working group aka DaWGs Supplemental meeting
15:30:35 <zodbot> Meeting started Thu Nov 19 15:30:35 2020 UTC.
15:30:35 <zodbot> This meeting is logged and archived in a public location.
15:30:35 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:30:35 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:30:35 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs_supplemental_meeting'
15:30:44 <samccann> #topic opening chatter
15:31:05 <samccann> who's around to rip the docs to shreds and put 'em back together, eh?  (aka split up the docsite)?
15:31:27 <samccann> #chair dmsimard
15:31:27 <zodbot> Current chairs: dmsimard samccann
15:31:51 <felixfontein> I'm partially around
15:31:59 <samccann> #chair felixfontein
15:31:59 <zodbot> Current chairs: dmsimard felixfontein samccann
15:32:14 <acozine> o/
15:32:22 <samccann> #chair acozine
15:32:22 <zodbot> Current chairs: acozine dmsimard felixfontein samccann
15:32:23 <lmodemal> Hello there o/
15:32:29 <samccann> #chair lmodemal
15:32:29 <zodbot> Current chairs: acozine dmsimard felixfontein lmodemal samccann
15:33:34 <acozine> andersson007_: baptistemm briantist cyberpear you folks interested in deconstructing and reconstructing docs?
15:34:01 <samccann> anyone else around to help us decide how to split ansible-core from Ansible the package documentation?  cybette JonTheNiceGuy ??
15:34:06 <abadger1999> Howdy
15:34:17 <samccann> hey!  good morning!
15:34:21 <samccann> #chair abadger1999
15:34:21 <zodbot> Current chairs: abadger1999 acozine dmsimard felixfontein lmodemal samccann
15:34:49 <acozine> hey abadger1999, good (early) morning
15:34:53 <samccann> ok gonna get us started for realz now
15:35:11 <samccann> #topic Creating a separate Ansible Collections Documentation site
15:35:59 <samccann> reminding us of the problem itself - Ansible the package will release as 3.0.0 in Feb, with an `ansible-core` of 2.10.  AKA two different release numbers and our docs are currently all tied to the `ansible-core` release number
15:36:12 <samccann> #info the current proposal - https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
15:36:27 <samccann> #info a hack of what this might look like - http://docs.testing.ansible.com/ansible/devel/
15:36:34 <acozine> then in April or May, ansible-core will release 2.11
15:36:59 <samccann> #info TL;DR; of the idea is to create a separate 'Ansible Collections Documentation' and move all scenario etc guides over there, plus the collection index.  And leave all the 'what is ansible, how to use ansible, etc on the existing site and call it Ansible Core Documentation
15:37:37 <samccann> So that's what I'd like us to focus on first.  Is ^^ a viable approach, without digging yet into how we could do it
15:38:30 <andersson007_> acozine deconstructing and reconstructing sounds intriguing:) i’m in the subway on the way home, so if there’s a summary of the discussion somewhere, I’d be happy to read it tomorrow
15:38:52 <samccann> andersson007_ - https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
15:39:00 <acozine> andersson007_: sounds good, we'll post the minutes later
15:39:20 <andersson007_> Cool thanks:)
15:39:32 <acozine> samccann: looking toward next summer, we will need docs for 2.9 (all-in-one), 2.10 (base-2.10-plus-collections), 3.0 (base-2.10-plus-collections) and 2.11 (ansible-core only) . . . have I left anything out?
15:39:52 <samccann> #info this is in 'interim' solution as there is more work/discussions on creating an improved docs.ansible.com overall.  But that is too far out to solve our immediate problem
15:39:56 <cybette> o/ (sorry I'm not able to 100% focus here for now, will try to catch up and check minutes as well)
15:40:09 <samccann> ok thanks cybette
15:40:42 <samccann> acozine - add Ansible 4.0.0 shortly after ansible-core 2.11 and I think you have our next 6-9 months
15:41:24 <samccann> So Ansible has 2.10, 3.0.0, and 4.0.0.  ansible-the-other-thing has ansible-base 2.10, ansible-core 2.11
15:41:38 <samccann> And then we have Ansible  the old way - 2.8, 2.9.
15:41:44 <acozine> heh, yep
15:42:12 <acozine> abadger1999:  do we know how many `ansible` versions will be maintained at a time?
15:42:28 <samccann> but focusing for the moment on Ansible Collections Documentation -  the big question is - Can we just point to Ansible Core for everything else
15:42:33 <acozine> will we stick to the traditional "latest and two back"?
15:42:48 <samccann> ^^ seems an implementation detail...
15:42:59 <abadger1999> acozine: It's complicated.  I've been telling people that only one version of post-2.10 ansible will be maintained at a time.  But I don't think it's sunk in with users yet.
15:43:03 <samccann> or do you see a problem with this proposal based on the number of older releases we might have?
15:43:08 <acozine> samccann: fair enough
15:43:30 <acozine> I'm trying to get a sense for how long the interim solution needs to last
15:43:30 <abadger1999> acozine: So there might be a lot of pressure to support older releases once we actually stop maintaining 2.10, 3.0, 4.0, etc.
15:43:31 <samccann> ok so.. back to - can we have Ansible Collections Docs
15:44:07 <abadger1999> 2.9 and before also will be supported for longer.  Probably under the latest +2 under the ansible-core umbrella.
15:44:25 <abadger1999> But downstream is likely to support 2.9 for a long time and I don't know how that will affect upstream.
15:44:27 <samccann> and if the reader needs details on using ansible or developing in ansible, they are pointed back to what is pretty close to our existing docsite
15:45:27 <acozine> samccann: yeah, the documentation on the general features of Ansible will feel familiar
15:47:07 <samccann> acozine: is that a 'vote' in favor of the current proposal?
15:47:22 <acozine> er, maybe???
15:47:25 <samccann> hehe
15:47:33 <samccann> at least at the moment not a vote against then
15:48:06 <samccann> Since we're not hearing a lot of yay or nay... how about we start listing what we can think of as pros or cons of this approach?
15:48:17 <acozine> I feel like we've been at this fork in the road before, and chosen not to go there, but I don't entirely remember why
15:48:46 * samccann dials up the wayback machine to ... summer 2019
15:49:10 <samccann> perhaps you are remembering our Great Debate on how to pull the collection docs back into docs.ansible.com?
15:49:11 <acozine> I wish I had a stronger sense of where we want to be in two or three years
15:49:53 <abadger1999> In this scenario, is it okay that the ansible.builtin documentation is in the collections documentation?
15:49:53 <acozine> if I had that, I would have more confidence that the choices we make now will provide both a solution to our immediate problem and a base for our longer-term goal
15:49:57 <samccann> maybe we can go back to older DAWGs meeting minutes on the older agenda page and see what we can find
15:50:50 <abadger1999> (I think it probably is except for a few things that are documented as part of the ansible.builtin collection but are really separate .... perhaps those can be fixed by merely moving the documentation out of the ansible.builtin module docs and into their own page)
15:51:06 <samccann> acozine - I haven't heard anything from The Powers That Be so I don't have any warm fuzzy that we can get direction this soon into their Grand Plan
15:51:09 <abadger1999> I'm thinking of things where FQCN don't work.
15:51:50 <samccann> abadger1999 - would it solve your worries if we had ansible.builtin repeated in Ansible Core Documentation and Ansible Collections Documentation?
15:52:37 <abadger1999> samccann: I don't think so.... however, that might be unavoidable....
15:52:38 <samccann> and acozine - i am reasonably confident that anything we do right now will end up partially trashed in a year.  But then I'm glass half empty gal
15:53:19 <abadger1999> samccann: Let's take April 2021 as a snapshot in time.... we'll have ansible-3.X.0 based on ansible-base-2.10   out and we'll also have ansible-core-2.11 out.
15:53:45 <samccann> we have approx 2 months of 'working time' to have a solution in place... and the docsite redesign effort internally anyway has yet to kickoff
15:54:09 <abadger1999> ansible-3.X will point at the ansible-base-2.10 documentation for documentation on the language.  But ansible-core-2.11 won't have an ansible-X.Y release to point at yet for its ansible.builtin documentation
15:54:22 <abadger1999> So that's why I think it's unavoidable.
15:54:39 <acozine> with docs for the ansible.builtin collection, we need to worry about the correct version showing up in the various places
15:54:41 <samccann> abadger1999 - yeah that's why I was thinking ansible.builtin stays with Ansible Core documentation for sure
15:54:56 <acozine> hm, we don't do that now
15:55:09 <samccann> not sure what the hmm references here
15:55:26 <abadger1999> Another question: How will links from collection docs and ansible-core work?
15:55:44 <samccann> abadger1999 intersphinx links?
15:56:40 <samccann> so if ansible.builtin exists only in Ansible Core (because that's the release it is tied to) - we could perhaps have a manual entry in Ansible Collections index to put a url back to Ansible Core for the builtin modules
15:56:52 <abadger1999> For that one, imagine after February.   ansible-base-2.10 is out.  It is used by both ansible-2.10 and ansible-3.0.0.  If I am on the ansible documentation, click a link to see something about the ansible language (so I go to the ansible-base docs) and then I want to go back to my ansible docs....... what sort of link will take me there?
15:57:22 <samccann> browser back button
15:57:48 <abadger1999> Yeah.  So will there not be any links from ansible-base to ansible?
15:57:54 <samccann> unless there's a sphinx way to always make a link open a different browser tab?
15:58:01 <abadger1999> Linking can only go one way?
15:58:10 <cybette> n00b question: will the search be global? i.e. if I am in Collections docs but want to search for something that's actually in the Core docs, will I still get the resultant links to Core docs?
15:58:12 <samccann> I think the only link from core to Ansible would be a top-level link
15:58:31 <samccann> cybette - no it won't. At least not today
15:58:44 <acozine> ah, because a link from the core docs won't have any way to know which version of Collections the user wants
15:58:50 <abadger1999> Yep.
15:58:54 <samccann> we may be able to improve search over time,
15:59:17 <abadger1999> So if that's the case, then we really will have to separate the ansible.builtin docs from the collection docs.
15:59:29 <abadger1999> Or duplicate them.
15:59:38 <samccann> #info if we split the docs - core vs Collections - we also impact search. Today it would be two independent searches
16:00:18 <cybette> ok, yeah, just thinking from user perspective, someone who may still be unclear what is where.
16:00:43 <samccann> abadger1999  could we pull 2.10 ansible.builtin into a 3.0.0 collection index?
16:00:44 <abadger1999> duplicating is nice so that the docs can be in the expected place with nice links for both ansible-core and ansible.  Not duplicating is nice because there will always be a canonical location for the latest information.
16:00:54 <acozine> would we have version-selection on both docsites? so on the Core side i could choose 2.9, 2.10, 2.11 and on the Collections side I could choose 2.10, 3.0?
16:01:05 <samccann> acozine - yes
16:01:15 <abadger1999> samccann: duplicate yes.  pointer would have to warn people that they have to use their browser's back button to get back
16:01:34 <abadger1999> (That's the same reason we have stub pages to switch to devel only pages, right?)
16:02:08 <samccann> so do we feel it's better to duplicate ansible.builtin to the Collection docs?
16:02:31 * samccann unsure how the SEO folks would feel about duplication
16:03:43 <samccann> #action samccann acozine - review old old DaWGs meeting minutes and other docs that described decisions when we created the docs pipeline but decided NOT to create a /collections/ url on the docsite
16:04:14 <acozine> duplicating content makes finding the right page from a search engine harder, but it makes moving from one page of the Ansible docs to the right/relevant next page of the Ansible docs easier
16:04:34 <samccann> yeah it seems like it
16:04:52 <abadger1999> The downside of duplicating is that ansible-2.10.7 will uses ansible-core-2.10.x where x is the latest version that's currently available.  The duplicated documentation content will, instead, reflect ansible-core-2.10.y where y is the latest version that was available when ansible-2.10.7 was released
16:05:19 <abadger1999> My guess is that's the lesser of the two evils?
16:05:28 <samccann> I'm trying to follow that statement...
16:05:52 <acozine> me too
16:06:02 <acozine> oh, because we build from the tip of the stable branch?
16:06:45 <samccann> ok so  I think what you are saying is that from the time an Ansible release goes out, there could be a separate, independent ansible-core dot release
16:06:48 <abadger1999> ansible-base-2.10.7 is the current version.  I release ansible-2.10.7.  The documentation is rebuilt and duplicates the contents in ansible-base-2.10.7 for ansible.builtin.  Then ansible-base-2.10.8 is released.
16:07:03 <samccann> So what we are duplicating is for a FUTURE version of ansible-core that isn't in Ansible?
16:07:43 <abadger1999> A user who then does `pip install --upgrade ansible` will get ansible-base-2.10.8 but the documentation of ansible.builtin will be for 2.10.7
16:08:34 <acozine> wouldn't they have to do `pip install --upgrade ansible-base`?
16:08:40 <samccann> but would that be solved if we rebuilt/republished the Ansible Collections docs for every Ansible and ansible-core release?
16:08:53 <abadger1999> I should have used separate versions for ansible and ansible-base there to make that clearer... (I can if you want me to)
16:09:44 <acozine> so if ansible-base 2.10.8 is current when we release 3.0 . . .
16:09:45 <samccann> ok I think my stumbling point is - I need to remember `ansible-core` is NOT part of the Ansible package, it's just installed/upgraded when someone installs Ansible?
16:09:59 <acozine> that's my confusion too
16:10:03 <abadger1999> acozine: unfortunately, no... `pip` will upgrade every package that gets touched in the dependency tree.  (Unlike yum which will only touch upgrade the package that's specified)
16:10:06 <samccann> so it will install/upgrade to whatever is the most recent `ansible-coree`?
16:10:12 <abadger1999> samccann: correct.
16:10:35 <felixfontein> also it would help if the docs would show the collection version, which in case of ansible.bultin is the ansible-base/ansible-core version
16:10:54 <acozine> ah, so knowing which version of `ansible` you have installed doesn't give you full information on what features you do/do not have, because users with the same version of `ansible` installed can have different versions of `ansible-core` installed
16:10:54 <samccann> So this leads me back to ansible.builtin doesn't get duplicated.
16:10:58 <abadger1999> samccann: yes, if we republish the collection docs both when ansible and when ansible-base update, that should solve that.
16:11:05 <samccann> omgosh my brain hurts now
16:11:43 <samccann> the problem is - Me as Susy User - installs Ansible 3.0.0, with ansible-core 2.10.x.  And I stay that way
16:12:25 <samccann> Meanwhile, ansible-core 2.10.y releases, we rerun the docsite generation, and BOOM, it now has ansible.builtin for a version of core that is NOT my Susy User version anymorew
16:12:47 <abadger1999> <nod>  For that, I think we have to rely on updated documentation containing info on what things have changed.
16:12:47 <samccann> since it was only an update to core, as an Ansible user, Susy User didn't upgrade
16:13:28 <acozine> yeah, Suzy User and Sarah User could both have Ansible 3.0.0 but have different ansible-core versions installed
16:14:02 <abadger1999> So the new documentation would say: "In ansible.builtin 2.10.3, the package parameter took a single string which was the name of a package  In 2.10.4, the package parameter can take either a string or a list of strings for multiple packages."
16:14:16 <samccann> #info we have to decide if we duplicate ansible.builtin to Ansible Collections and rebuild for every ansible-base release, how do we handl the folks who upgrade only based on Ansible releases? They won't get the updated ansible-base until the next Ansible release, but the docs will already be on that future ansible-base release
16:14:35 <samccann> abadger1999 yeah but nobody writes that level of information today
16:14:54 <acozine> we need a "pick-n -mix" docsite with double dropdowns for My Ansible Version and My ansible-core version with an AI behind the scenes that delivers version-specific documentation on demand!
16:14:55 <samccann> I mean in the changelogs sure... and maybe it shows up in the porting guide entries if it's really important
16:15:07 <samccann> acozine++  haha yep!
16:15:15 <abadger1999> <nod>  That problem solves other version mismatches too.  So we probably should "encourage" people do that.
16:15:50 <samccann> Ok so when ansible-base releases, Ansible will release within what... 3 weeks max?
16:16:01 <samccann> (for these patch releases we are debating)
16:16:10 <abadger1999> For instance, "I inherited this playbook which my predecessor wrote for ansible-2.9.5.  The yum: task is  broken with ansible-2.12.0.  How can I tell what I need to change now"
16:16:50 <abadger1999> samccann: yeah, should be three weeks max since ansible patch releases are on a three-week release schedule.
16:17:41 <samccann> so our other option - we do NOT update the Collection docs when `ansible-base` releases.  We keep t hat docsite focused only on those doing an Ansible upgrade when Ansible releases.  At worst, it is a 3 week delay
16:18:11 <dericcrago> is / does `ansible --version` going to print out all of the relevant versions for users to be able to look up the appropriate documentation?
16:18:14 <samccann> as in - we support the folks upgrading Ansible when it needs it, not upgrading Ansible in between
16:19:09 <samccann> alternate 2 - we don't duplicate ansible.builtin at all.  And then yeah, it depends on `ansible --version` letting the user know which version of ansible-core they have to know which version to look up on the docsite
16:19:17 <felixfontein> dericcrago: `ansible --version` shows the ansible-base/ansible-core version, and nothing related to the ansible version
16:19:48 <dericcrago> so when I install ansible 3.0.0 `ansible --version` is going to tell me 2.11?
16:19:54 <felixfontein> dericcrago: compare `ansible --version` to `ansible-playbook --version`
16:19:55 <felixfontein> dericcrago: yes
16:20:04 * samccann brain hurting even more now
16:20:13 <dericcrago> I can't see that tripping anyone up ;)
16:20:32 <felixfontein> dericcrago: it's already fun right now, when people are asked in issues to tell the 'ansible version'
16:20:41 <abadger1999> dericcrago: core was going to change that.... although I don't know what to.
16:20:43 <felixfontein> most do `ansible --version`. which is not the same. but right now, close enough
16:21:08 <acozine> so only `pip show ansible` (or is it pip list???) will give the Ansible version?
16:21:20 <samccann> felixfontein - is there an issue or PR tracking a solution to that particular problem? So someone could eventually tell which Ansible package version they have installed?
16:21:32 <abadger1999> if it says ansible-base 2.10.5, that would help.  But it would be even better if it also said the ansible package version
16:22:30 <abadger1999> acozine: yes, I think so.
16:22:37 <felixfontein> abadger1999: I think we had this discussion at a public project meeting once, and it was rejected
16:22:42 <felixfontein> (IIRC)
16:22:55 <felixfontein> samccann: I'm not aware of one
16:23:04 <abadger1999> Okay... I had the discussion with them on internal slack but that could have been before the public meeting.
16:23:19 <abadger1999> (It feels like about a month ago now)
16:23:23 <bcoca> its not normaly for cli tools to return the package version, normally job of pkg manager
16:23:23 <samccann> #action - open a docs PR  to explain how to determine ansible-base version vs Ansible package version...`ansible --version` is base, `pip show ansible` is Ansible version
16:23:48 <samccann> ok back to discussing the docs proposal
16:23:50 <bcoca> samccann: that also assumes ansible was installed via pip
16:24:14 <felixfontein> https://github.com/ansible/community/issues/560#issuecomment-700723990 https://meetbot.fedoraproject.org/ansible-meeting/2020-09-29/ansbile_core_irc_public_meeting.2020-09-29-18.58.log.html
16:24:20 <acozine> bcoca: is there any other way to install the standard/versioned core-plus-collections `ansible`?
16:24:24 <abadger1999> samccann: (1) might want to use pip show for both. (2) there might be cornercases where pip doesn't work but it should work in most instances
16:24:31 <samccann> we are somewhat stuck on what to do about ansible.builtin  - duplicate or not duplicate.  We can continue that one later... are there other ideas/problems we want to debate about the Collection docs proposal?
16:24:45 <abadger1999> Even though linux distros don't install via pip, the metadata that pip needs is usally included in the distro packages
16:24:48 <bcoca> acozine: distros can package it and create rpm/deb/etc easiliy, they have in past and some peopel arleady do their own rpms
16:25:02 <samccann> #info could use pip show for both ansible-core and Ansible  but doesn't solve the problem for those who don't install w/ pip
16:25:06 <bcoca> ^ one example, pip is not installed in rhel by default
16:25:11 <abadger1999> samccann: So you might want to tell people to use pip show for getting the ansible-core version as well.
16:25:13 <samccann> to be honest, docs can't solve the problem for everything
16:25:14 <felixfontein> 19:22:36 <nitzmahone> Anyway, I think we should work on clarifying what the version displayed actually is, but I'm -1 for adding `ansible` version to that output, as it's not actually useful for much IMO
16:25:40 <bcoca> samccann: ' pip ... or use the package manager from your OS '
16:26:22 <samccann> #info could say ' pip ... or use the package manager from your OS'
16:26:24 <samccann> thanks bcoca
16:26:25 <abadger1999> felixfontein: Ah, I think I had my discussion afterwards.
16:26:38 <abadger1999> felixfontein: I think I saw that comment in the public meeting logs and brought it up afterwards.
16:26:40 <samccann> back to the Collections docs... what other problems does it have that we should discuss?
16:26:54 <bcoca> samccann: would not make you list every possible package manager and way to query, generic message should be enough
16:27:22 <felixfontein> abadger1999: I haven't really followed-up afterwards and forgot most of what was said in the public discussion, I just remembered 'probably won't happen'
16:27:42 <abadger1999> <nod>
16:28:19 <abadger1999> nitzmahone probably should have followedup afterwards since he was leaning towards doing something; just not showing the ansible version.
16:28:38 <acozine> samccann: looking at your mockup (nice work!) I think my biggest questions is, where should the "overarching" actions be documented?
16:28:44 <abadger1999> (ie, something like the `ansible-base package version is 2.10.0`)
16:29:20 <acozine> for example, in a Collections site, would `Installing Ansible` be about installing ansible-core, installing ansible, installing individual collections, all of the above?
16:29:43 <acozine> s/`Installing Ansible`/`Installation Guide`/g
16:30:01 <bcoca> abadger1999: last i looked it was `/usr/bin/ansbile 'ansible-base' 2.x.y`
16:30:08 <acozine> where do we document  "How Ansible fits together"?
16:31:02 <acozine> as in, "there's this thing called ansible-core and then there are collections and you can put them together in two different ways, either by using the Ansible package or by installing selected collections"
16:31:12 <samccann> acozine - Installing Ansible in the Collections docs is installing the package.  The Using Collections guide talkes about installing individual collections (at least it does today)
16:31:28 <samccann> How Ansible fits together probably needs to be described in both
16:32:07 <acozine> then do we have an `Installation Guide` on the ansible-core side as well?
16:32:07 <samccann> And Installing Ansible in Ansible Core docs would be renamed to Installing `ansible-core`.
16:32:28 <abadger1999> felixfontein: You'll just have to ask him when he plans to add that.
16:32:28 <samccann> yeah sorry we do. They will be 'very similar' but one will install core and the other the package
16:32:48 <acozine> heh, no need to be sorry
16:33:05 <acozine> just thinking it through
16:33:30 <acozine> and thinking about how we tell Google which one is which and what users are likely to want
16:33:41 <felixfontein> abadger1999: would still be nice if `ansible --version` could also output the Ansible version :)
16:34:09 <acozine> and if we do pull together consolidated site search, how we differentiate the two Installation Guides there
16:34:10 <samccann> so I think both would have cannonical_url set for latest, same as we do today
16:34:12 <abadger1999> felixfontein: yeah...... maybe that's something to ask gundalow about.
16:34:23 <samccann> and I think we do NOT duplicate ansible.builtin.
16:34:29 <abadger1999> felixfontein: he should be able to say "we need this"
16:34:52 <samccann> acozine - the installation guides will need unique names.  What is a bigger problem - Using Collections
16:35:11 <samccann> both docsites need Using collections... you can do it on core, you can do it with Ansible the package
16:35:55 <samccann> but then we are at the same state that the rest of Red Hat is - 'modularize' documentation by definition means the same docs appear in more than one location.
16:36:12 <acozine> yeah
16:36:36 <abadger1999> isn't using collections part of the ansible-base docs that we have to point to?
16:36:37 <acozine> maybe the next step on the info-architecture side is an outline?
16:36:49 <abadger1999> since it's part of the core language.
16:36:54 <samccann> #info how to we handle google search when we duplicate docs such as installing and using collections vs cannonical url
16:36:56 <abadger1999> s/language/framework/
16:37:08 <samccann> abadger1999  -yes.
16:37:32 <samccann> but I was thinking of duplicating 'using collections' in the Ansible Collections Docs... because... well... it's called Ansible Collections docs :-)
16:37:47 <abadger1999> <nod>
16:38:22 <abadger1999> I guess the same pros and cons as duplicating versus pointing for ansible.builtin apply here.
16:38:22 <samccann> But you are correct, it is  tied to base/core, not Ansible the package.  Which means we'd have to magically pull the Using Collections' version of the rst file from say ansible/ansible 2.10 and into Ansible 3.0.0 docs.  Which I dunno how to do in git land
16:39:12 <acozine> in some ways, there are two different ways to think about an Ansible Collections site - 1. as documentation for the "kitchen sink" Ansible package, and 2. as documentation for collections as add-ons
16:39:18 <samccann> The other approach, which I KNOW we considered way back in the docs pipleline design days... is we just have a /collections/ url that has the collection index that matches the Ansible package.. .and the matching scenario etc guides
16:39:29 <abadger1999> samccann: We can do that. it feels a little hacky, but I need  a copy of the ansible release to build docs and so I can copy on a file-by-file basis anything that we need.
16:39:39 <abadger1999> I don't know that it's a good idea, but it is possible ;-)
16:39:47 <samccann> heh thanks
16:40:15 <abadger1999> acozine: +1
16:40:27 <samccann> acozine - I think part of the problem is that 'back in the day' Ansible the package is what we wanted everyone using. That idea is changing in the downstream world anyway
16:40:36 <abadger1999> acozine: do we need to choose one of those two ways of looking at it or are we going to try to satisfy both?
16:40:47 <samccann> But the 'lets keep Ansible as Ansible  the package' decision is what we are struggling with now.
16:41:39 <bcoca> why initially we chose 2 names, its fine changing the decision, but no time was made to handle the drawbacks nor were the KNOWN items scheduled to be addressed
16:41:57 * gundalow returns
16:42:10 <samccann> ^^^ sounds like the title of a superhero movie!
16:42:17 <samccann> Gundalow Returns!
16:42:42 <acozine> we'll always have some users who take each approach to *using* Ansible, but I think we should choose a way to look at the docsite, then figure out how we build it so that users who have the other idea can find what they need
16:43:07 <acozine> yeah, downstream nobody will use ansible the package
16:43:36 <acozine> there a pros and cons to each, I expect
16:43:40 <samccann> So it feels like a Community Team decision at this point.
16:44:06 <acozine> but if we don't agree on a basic approach, we'll have double the duplication, is my guess
16:44:38 <abadger1999> ax<nod>  But also.... the plan is that downstream, no one will consciously use the ansible-base package either.
16:44:43 <samccann> Can we go to the approach we discarded 'way back when' of a /collections/ url that holds the Collection index for Ansible the Package, and the scenario/platform guides.  And everything else stays in Ansible Core docs
16:44:57 <abadger1999> downstream is just confusing for a few cycles.
16:45:47 <abadger1999> samccann: I'd put the ansible.bultin docs into the /collections/ url then.
16:46:02 <abadger1999> well.... hmm..
16:46:13 <abadger1999> okay.... we started off taling about version mismatches.
16:46:14 <acozine> samccann: that would also support moving content into collection `/docs/` folders over time
16:46:29 <abadger1999> and thinking about it this way brings us back to that.
16:46:32 <acozine> yeah, the versioning is the main stumbling block there
16:46:46 <acozine> originally we were not going to version collection docs
16:47:27 <bcoca> yeah, never saw how that would work
16:47:56 <samccann> unfortunately we do have to version collection docs because we will have more than one Ansible the Package version released, right?
16:48:06 <acozine> yes, I think so
16:48:47 <acozine> so then we're back to "how does a user move between the correct version of the collections docs and the correct version of the core docs?"
16:48:53 <samccann> ok so.. feel of the meeting at the moment - it seems like we want to (re)evaluate the idea of Ansible Collections Documentation being JUST the collection index and scenario guides... Does that sound right?
16:49:01 <abadger1999> idea.... Lot of work but it's an idea.
16:49:23 <abadger1999> colletion docs are unversioned.
16:49:38 <abadger1999> Instead, the docs say which version of ansible/ansible-base they are a part of.
16:50:11 <bcoca> let AH/galaxy deal with collecitno versioned docs? only tie ansible docs to 'shipped'?
16:50:28 <samccann> does it today (either of them?)
16:50:30 <bcoca> but you should at least document somwhere collection versions shipped
16:50:39 <bcoca> samccann: afaict not yet
16:50:44 <abadger1999> One major change from that is it becomes extremely important that collection docs document when changes happened (the package became a list example earlier) because there won't be older versions of hte docs at all to refer to.
16:50:50 <acozine> right now there's no way to display full module docs on Galaxy at all, let alone multiple versions
16:51:12 <samccann> yep.
16:51:40 <abadger1999> And galaxy docs will never be "the same" as docs.ansible.com.... the design of galaxy is that each collection is an isolated entity.
16:51:49 <acozine> bcoca: when I'm talking about "versioned" for collection docs, I mean the shipped version
16:52:06 <samccann> ok I have a hard stop in 5 minutes.  What's our next steps?
16:52:13 <abadger1999> So documentation for  things that cross collections (like amazon.aws and community.aws) will never work as well on galaxy as they will on docs.a.c
16:52:14 <bcoca> version of collecitno shippped or ansible version?
16:52:21 <bcoca> .ENOTOOMANYVERSIONS ...
16:53:06 <acozine> samccann: maybe a pro/con list for a couple of possible ways forward? and/or an outline of which content would go where?
16:53:44 <abadger1999> acozine, samccann : hmmm... okay, problem with my idea..... the docs build would have to know about the history of releases in order to auto-generate info on what ansible and ansible-base releases a plugin is part of.
16:53:51 * bcoca is very happy ansible-doc only deals with 'current'
16:54:10 <acozine> yeah, `ansible-doc` already knows which version the user has installed
16:54:23 <bcoca> and doesnt care, there can only be one!
16:54:30 <abadger1999> I guess that falls into possible, but a ton of redesign.
16:55:54 <samccann> #action samccann to create pro/con list for the different way forward and/or an outline of which content goes where
16:56:22 <samccann> ok I need to prep for next meeting.  Do y'all want to continue here, or should I close out this meeting for the current meeting notes?
16:56:30 <acozine> I guess another option is to say docs.ansible.com documents the community distro only, and push documentation for ansible-core versions that differ from the community distro downstream . . . the downstream docs are not behind a paywall
16:57:01 <acozine> samccann: I have another meeting also
16:57:11 <acozine> I vote to close this one out
16:57:28 <abadger1999> <nod>
16:57:30 <samccann> ok gonna close it since both docs folks have to leave
16:57:34 <samccann> thanks everyone!!
16:57:45 <acozine> thanks samccann for keeping us moving!
16:57:48 <lmodemal> Thanks all!
16:57:54 <samccann> #endmeeting