15:31:38 <acozine> #startmeeting DaWGs supplemental meeting aka The Great Docsite Split of 2021
15:31:38 <zodbot> Meeting started Thu Dec  3 15:31:38 2020 UTC.
15:31:38 <zodbot> This meeting is logged and archived in a public location.
15:31:38 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:31:38 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:31:38 <zodbot> The meeting name has been set to 'dawgs_supplemental_meeting_aka_the_great_docsite_split_of_2021'
15:31:40 <felixfontein> I won't really be around this time unfortunately
15:31:47 <acozine> felixfontein: we'll miss you
15:32:26 <acozine> #topic opening chatter
15:32:56 <acozine> who's available to talk about collection docs vs. core docs?
15:33:00 <samccann> felixfontein - can you add your feedback to the doc when you get a chance? or here in irc - https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
15:33:07 <samccann> o/
15:33:25 <acozine> #chair samccann
15:33:25 <zodbot> Current chairs: acozine samccann
15:33:37 * dericcrago waves
15:33:43 <acozine> #chair dericcrago
15:33:43 <zodbot> Current chairs: acozine dericcrago samccann
15:34:01 <felixfontein> samccann: probably not today, but I'll try tomorrow :)
15:34:15 <samccann> thanks!
15:34:58 <acozine> gundalow: dmsimard aminvakil andersson007_ briantist cyberpear madonius persysted tadeboro tremble pinging you as recent participants
15:35:08 <cyberpear> o/
15:35:09 <acozine> there are seats at the table for everyone
15:35:28 <acozine> if you are watching this chat and have never participated, you are welcome to join us!
15:35:31 <acozine> #chair cyberpear
15:35:31 <zodbot> Current chairs: acozine cyberpear dericcrago samccann
15:35:43 <lmodemal> Hello o/
15:35:49 <acozine> #chair lmodemal
15:35:49 <zodbot> Current chairs: acozine cyberpear dericcrago lmodemal samccann
15:35:57 <dmsimard> \o
15:36:02 <acozine> #chair dmsimard
15:36:02 <zodbot> Current chairs: acozine cyberpear dericcrago dmsimard lmodemal samccann
15:36:46 <acozine> our current working document is: https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
15:37:02 <acozine> thanks everybody for turning up and tuning in!
15:38:36 <acozine> and special thanks to samccann for doing a ton of work to show how we can make our docs keep up with the diverging version numbers of Ansible (the kitchen-sink distro) and ansible-core
15:39:05 <samccann> :-)
15:39:08 <acozine> in addition to the working document, we have hacked examples of what the proposed solution could look like
15:39:16 * dmsimard looks at doc
15:39:32 <acozine> hacked ansible-collections docsite: http://docs.testing.ansible.com/ansible/2.11/
15:39:47 <acozine> hacked ansible-core docsite: http://docs.testing.ansible.com/ansible/devel/
15:39:52 <samccann> #info draft proposal doc https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
15:40:08 <samccann> #info hacked ansible-collections docsite: http://docs.testing.ansible.com/ansible/2.11/
15:40:22 <samccann> #info  hacked ansible-core docsite: http://docs.testing.ansible.com/ansible/devel/
15:40:38 <acozine> # info hacked docsites will disappear without warning in a few weeks
15:40:42 <acozine> grr
15:40:54 <acozine> #info hacked docsites will disappear without warning in a few weeks
15:41:09 <samccann> #info The guiding principle here is that the Ansible Collections Documentation includes only the scenario/platform guides specific to those collections, and the overall collection index. Everything else is really based on the version of ansible-core included and is thus in the Ansible Core Documentation.
15:41:25 * acozine will someday get all the IRC meeting commands into her muscle memory
15:42:04 <acozine> #topic Which documentation topics/sections will end up where
15:43:03 <acozine> samccann: on the hacked ansible-collections site on the testing URL, there's a section for `Using and Developing Ansible`
15:43:04 <samccann> as currently proposed, all the user and developer topics stay on ansible-core.  All collections scenarios etc and the collection index move to ansible-collections
15:43:19 <samccann> yeah it's just a pointer as I figured folks would look for that
15:43:31 <samccann> So it's an rst page to say 'go here'
15:43:36 <acozine> ah, so that would be a stub page with links back to the ansible-core docs?
15:43:41 <samccann> yep
15:45:09 <acozine> cool
15:46:19 <acozine> maybe a good next step is to look at the TBD section?
15:46:51 <samccann> how about we go over the pros/cons first?
15:46:55 <acozine> sure
15:47:07 <acozine> #topic pros and cons of splitting the docs
15:47:11 <samccann> that way people can pipe in on where they see problems with the current split
15:48:17 <samccann> I think the cons involve - readers hopping between sites, and is there Ansible package info that shouldn't be on the ansible-core docs?
15:49:06 <samccann> on the hopping - if we make the split as clean as possible - it becomes obvious that "i want to figure out this feature, or how to do this thing' is ansible-core'  and 'i want to figure out this feature in this collection' is ansible-collection
15:49:09 <acozine> can you say more about "is there Ansible package info that shouldn't be on the ansible-core docs"?
15:49:15 <samccann> Sure
15:49:28 <dmsimard> samccann: what about modules and plugins in ansible-core ?
15:49:32 <samccann> The recent discussions of 'I want my collection to be in Ansible package.. what are the requirements"
15:49:51 <samccann> and yes dmsimard - that is the other contentious area - ansible.builtin
15:50:05 <dmsimard> right, is ansible.builtin considered a collection ?
15:50:06 <dmsimard> or core ?
15:50:12 <samccann> we can either duplicate ansible.builtin, or put a pointer from ansible-collections back to core
15:50:32 <samccann> it's both.. it is a collection, but it is also part of core. So needs to have some reference in both.
15:50:38 <acozine> IIRC the long-term roadmap involves disentangling the ansible.builtin modules from core
15:50:49 <samccann> For searchability, it should be in ansible-collections
15:51:03 <samccann> for 'complete docset' it should be in ansible-core.
15:51:48 <dmsimard> samccann: +1 for including in ansible-collections
15:51:49 <samccann> Given what acozine just said we either duplicate it for now, or put it in collections and add a manual pointer in core to point over to its home in collections (a stub page)
15:52:05 <acozine> the original plan for collections was to remove ALL modules from core, but that turned out to be more difficult than expected
15:53:50 <samccann> ok so seems like it should definitely be in ansible-collections, and then we can talk to toshio later on how easy/difficult it  would be to duplicate it on ansible-core for now.
15:54:12 <samccann> But the duplication has drawbacks for search results - which one ends up getting priority etc and does it confuse users to find it in both places etc
15:55:02 <samccann> and my 'nickel' guess is that they will get out of sync from time to time.  Imagine a fix/new parameter going into /devel/ and being updated that night in the docs on ansible-core... but not getting updated on ansible-collections for maybe 3 weeks
15:55:38 <dmsimard> not an easy problem
15:55:39 <samccann> but if it doesn't get updated on /devel/ then we upset the developers making those fixes/enhancements etc
15:55:40 <acozine> that would reflect reality
15:56:03 <samccann> yeah so thinking it needs to be in both places until it is removed from core
15:56:23 <acozine> because that fix in devel would not be available to users of the Ansible package until the new ansible-core gets released and a new Ansible that points to the new ansible-core gets released as well
15:57:03 <samccann> yep. but is available to core users.. thus.. needs to live in both places
15:57:33 <acozine> agreed
15:57:49 <acozine> though I suppose we could restrict that to the `devel` branch
15:57:59 <acozine> if we want to de-duplicate for SEO reasons
15:58:26 <acozine> we're going to need some kind of diagram before long, I think ;-)
15:58:30 <samccann> we would still have problems with core-2.12 going out before Ansible 4.0.0... and thus the /latest/ doesn't show what's avialable to core-only users
15:59:22 <samccann> so I'm still leaning toward - if it's in core, it's docs are in core... and then we duplicate only what is mandatory (ansible.builtin that matches the Ansible release)
16:00:25 <samccann> my uneducated guess is that search results will linger with returning ansible-core for builtin plugins until we remove them entirely
16:00:27 <acozine> that's true, in the interval between the release of a new ansible-core version and the release of a new Ansible version that uses that ansible-core version, changes to the builtin modules will need to be documented in latest and in devel for ansible-core
16:00:39 <acozine> samccann: probably true
16:01:18 <samccann> we could potentially add to the top banner of those plugin pages to add a pointer to 'for the full collection index go here'
16:02:02 <acozine> that's a good idea
16:02:17 <samccann> #info we should duplicate ansible.builtin on both docsites until those plugins are removed from core. Core users will need that info Ansible package docsite updates won't be in sync with core releases.
16:02:29 <dmsimard> makes sense
16:02:47 <acozine> though I suspect that most people who hit a `builtin.my_plugin` page from a search engine get the info they want/need on that page and go no further
16:02:53 <samccann> #info consider adding to the core banner for those plugins 'for the full collection index go here' to point to ansible-collections
16:03:15 <samccann> true
16:03:23 <acozine> on the other hand, providing links is generally a good idea
16:03:35 <samccann> Should we move to the next trouble child - guidelines for being included in the Ansible package?
16:03:53 <samccann> aka the stuff currently being discussed in the community meeting.  Where would that doc live eventually?
16:03:59 <acozine> is that still part of Pros and Cons?
16:04:09 <samccann> it's a new part of that yeah
16:04:23 <acozine> okay
16:04:24 <samccann> though I could just add it to the TBD and we can stick w/ the pros/cons list
16:04:56 <acozine> so the tension is between "it's developer docs, all developer docs belong with ansible-core" and "it's documentation about collections, all collections docs belong with ansible-collections"?
16:05:09 <samccann> just added it to tbd so we can continue w/ the existing pros/cons list
16:05:21 <samccann> but yeah that's the tension
16:05:21 <acozine> samccann: sounds good
16:05:41 <samccann> So the next cons - handling latest (and who's latest is latest!)
16:06:17 <samccann> So if we keep all the .rst files in ansible/ansible - i'm not sure how we can mark latest that matches both ansible-core for its rst files, and ansible-collections for its rst files
16:06:37 <samccann> That particular problem goes away if we move all the rst files to say `ansible-collections/docs' repo
16:06:51 <samccann> to elaborate
16:07:07 <samccann> currently the latest and cannonical url info is in one sphinx file - conf.py
16:07:48 <samccann> there may be some fancy way we can support two  conf.py files in ansible/ansible (again, toshio might know better here).
16:08:10 <samccann> But so long as we have collection rst files in ansible/ansible - we are tied to their release/branching names etc
16:08:51 <samccann> my gut feeling is - move the collection rst files. But I know that's a big step to consider... and opens up the pandoras box of ' why not move all the docs out of core' which I'm personally against.
16:09:10 <dmsimard> which collection rst files are those ?
16:09:23 <samccann> scenario guides, network guides mostly
16:10:10 <samccann> the collection index doesn't actually 'exist' in either repo, it's generated at build time by anstibull
16:10:13 <acozine> it's mostly pages that should probably end up in collections-based `/docs/` folders eventually, when GalaxyNG is able to display those
16:10:18 <dmsimard> could they belong in individual collections and not necessarily in a catchall docs repo ?
16:10:26 <samccann> some yes, some no
16:10:34 <samccann> network user guide covers a bunch of collections
16:10:47 <samccann> AWS likely does for at least two collections today. etc etc
16:11:03 <samccann> even vmware I think spans 2-3 collections
16:11:32 <dmsimard> are those organic leftovers from the various incomplete migrations or are they there on purpose ?
16:11:41 <samccann> on purpose.
16:11:46 <dmsimard> apologies for the simple questions, still learning a lot :D
16:11:57 <acozine> those are good questions dmsimard
16:12:07 <samccann> well, the network one is.  There are broad categories of information that is applicable to a bunch of individual collections.
16:12:59 <dmsimard> so these would be more... "ansible" docs rather than "ansible-core" docs
16:13:00 <samccann> For vmware - just going based on a few rst files i've reviewed - it's possible it could be split up and put in the appropriate collection-specific /docs/ folders
16:13:02 <acozine> we're also developing content for security applications for Ansible
16:13:07 <dmsimard> as in they aren't specific to core
16:13:12 <acozine> those docs will also be multi-collection
16:13:26 <samccann> correct, these are specifically NOT core docs. They are tied to one or more set of collections
16:13:57 <dmsimard> ok, thanks for clarifying :)
16:15:34 <samccann> so the pros of moving these scenario guides to ansible-collections repo 'somewhere' is it gives us the independent release/publishing we need. and puts them at least closer to the repos where they apply. Easily solves most of the /latest/ problems etc
16:15:38 <samccann> the cons ?
16:16:05 <acozine> it might make them harder to find
16:16:17 <samccann> one con would be Edit on Github is broken until Ansible 4.0.0 I think. Because we would be midstream in moving files etc.
16:16:43 <samccann> another con - they would disappear from ansible-core docs likely before we publish Ansible collections docs
16:16:49 <samccann> for devel only that is
16:17:18 <samccann> I'm not following harder to find?
16:17:48 <samccann> they are all there in the proposed Ansible collections doc markup - http://docs.testing.ansible.com/ansible/2.11/index.html
16:17:57 <acozine> it's a bit hazy even in my mind, tryng to think about challenges
16:18:26 <acozine> I guess search engines will update the indices pretty quickly
16:18:36 <acozine> so searches should return the new URLs
16:18:45 <samccann> yes eventually
16:19:10 <samccann> but that brings up the other /latest/ problem - When Ansible Collections 3.0.0 releases, it should be marked 'latest'
16:19:11 <acozine> if folks are used to finding the Scenario Guides in the "main docs" they may be confused, but we can leave a stub page
16:19:28 <acozine> as I think it through, probably not a serious problem
16:19:31 <samccann> but ansible-core 2.10 will still have latest on those exact same guides... because we won't touch ansible-core (aka current docs)
16:20:05 <acozine> well, we could if we really wanted to
16:20:15 <samccann> #info consider interim stub pages on ansible-core-2.11 to show where all the scenario etc guides have moved to
16:20:38 <acozine> I mean, we could backport the removal/stub
16:20:47 <samccann> We can't
16:20:55 <acozine> no?
16:20:56 <samccann> because 2.10 today HAS to cover both ansible-core and Ansible the package
16:21:14 <samccann> unless we want to create an Ansible Collections 2.10 docsite.. .which we seriously don't have the time to do I think
16:21:47 <samccann> i feel like the docsite split goes well with the version differences.  Oh this is Ansible 3.0.0? well okay yeah sure it has a separate docsite now
16:22:59 <dmsimard> nit: no such thing as ansible-core 2.10
16:23:04 <dmsimard> it's either ansible-base 2.10 or ansible-core 2.11
16:23:09 <acozine> heh
16:23:10 <samccann> heh yeah theres that too
16:24:00 <samccann> #info general problems with latest https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both#How-to-handle-latest
16:24:10 <samccann> #topic handling /latest/
16:24:20 <samccann> Since that's what we are discussing now
16:24:30 <acozine> heh
16:25:04 <samccann> so what I don't have written there, but should add - Ansible 3.0.0 does NOT get /latest/ at all
16:25:35 <acozine> as in, we move away from using `latest` altogether for the collections docs?
16:25:36 <samccann> because it would cause a latest clash with 2.10.
16:25:54 <samccann> we could bring it back for Ansible 4.0.0
16:25:56 <acozine> that depends on the "level" we choose for the new docsite
16:26:25 <acozine> if the new site is `docs.ansible.com/ansible-collections` then it can have its own `latest`
16:26:40 <samccann> it's still a problem child
16:27:09 <samccann> So let's ignore 3.0.0 for now, because things will be 'in flux' from the docs perspective, and jump to Ansible 4.0.0 marked as latest
16:27:25 <samccann> it depends on ansible-core 2.11... which is also latest. it all makes sense
16:28:13 <samccann> Same thing for 5.0.0 for a time
16:28:15 <samccann> Ansible core 2.12 becomes /latest/. For some period (a month? maybe 2?) Ansible 5.0.0 is /latest/ but now must point to Ansible core 2.11, which is no longer /latest/. While we can update our urls appropriately, it will confuse readers who just go between the sites on their own. They now have to remember anything added in ansible-core 2.12 is not yet available to them, even though they will get /latest/ urls from google searches etc.
16:28:58 <dmsimard> for posterity, proposed schedule for 3.0 https://hackmd.io/y7BBcweNR3aRVLuMbKkDxw?view
16:29:25 <dmsimard> going with that timeline, 3.0 would still ship 2.10 and then flip to 2.11 in 4.0
16:29:45 <samccann> yeah that's one of the reasons I wanted to jump to 5.0.0
16:29:52 <acozine> That will definitely be confusing, but again it will reflect reality - ansible-core users will have access to features that Ansible-the-kitchen-sink-distro users will not.
16:30:13 <samccann> to ignore the current 'we are moving files around' problem and get to the - this will happen multiple times in the future
16:30:27 <acozine> Yes, it will happen with every release of ansible-core
16:30:36 <samccann> yep
16:31:10 <samccann> But just  to keep thinking out loud - if we drop the /latest/ convention from ansible-collections docs... what problems does that create?
16:31:26 <dmsimard> what would you replace latest with ? the version number ?
16:31:29 <samccann> we 'can' I think still have a cannonical url that gets updated with each Ansible the package release
16:31:32 <samccann> yes
16:32:30 <acozine> using `latest` means that blog posts and other outside links can be permanent, in the sense that a link to `docs.ansible.com/whatever-product/latest/my-page.html` never (or very rarely) needs updating
16:33:04 <acozine> so `latest` means we end up with fewer reddit links to ancient pages that we cannot get rid of
16:33:14 <samccann> #info the /latest/ convention solves the problems of personal/blogpost links going stale. if they link to a /latest/ page, it always stays valid
16:34:12 <samccann> ok thanks. just wanted to think down that path. So keeping /latest/ seems the better approach, and just living with that twice a year 'lag' between when core releases and goes latest vs when Ansible picks up that core version in its latest
16:34:45 <acozine> whether or not we use `latest` for the collections docs, we still have the problem that some versions Ansible will incorporate an older version of ansible-core
16:35:14 <samccann> true
16:35:21 <dmsimard> acozine: can you elaborate on older ?
16:35:27 <acozine> the main challenge is helping users understand which version of what thing they have installed, how to find documentation for how that version of that thing works
16:35:37 <dmsimard> the version number of ansible-core will always be behind ansible moving forward
16:36:10 <acozine> dmsimard: what samccann was saying earlier - there will always be a period when there's a new ansible-core release available, but Ansible is still using the previous ansible-core version
16:36:35 <dmsimard> right, ok, thanks
16:36:48 <samccann> #info make sure any links from ansible-collections to ansible-core docs uses the version specific url, not /latest/ so it matches the core version used w. Ansible
16:37:01 <dmsimard> I think the intent is to minimize that gap as much as possible fwiw
16:37:03 <acozine> but this is a specific instance of a more general problem
16:37:34 <dmsimard> like 4.0 is essentially synchronizing with the 2.11 release and I expect we'll want to do that in the future as well
16:37:35 <acozine> each Ansible version incorporates a specific ansible-base or ansible-core version
16:37:50 <dmsimard> not necessarily specific, it's a bound
16:37:58 <dmsimard> as in, it's not pinned
16:38:09 <samccann> yeah so there will always be say a 2-3 week gap between the /latest/ of each when core releases
16:38:13 <acozine> ah, so it's `2.11 max`?
16:38:18 <acozine> dmsimard: ^^^
16:38:49 <dmsimard> acozine: yes, I don't have a setup.py handy to get a copy/paste from but it's something like "ansible-base>=2.10.x,<2.11"
16:39:03 <acozine> okay, thanks
16:39:39 <acozine> so the challenge boils down to: help the user figure out which version of each thing they have installed and how to find the right docs for that version of each thing
16:40:09 <samccann> ok we are past the 1 hr mark. I have a hard-stop at noon (20 min) - do we want  to discuss the TBD items? or call it a meeting?
16:40:51 <samccann> #info general feeling so far is to keep /latest/ for both docsites
16:42:00 <acozine> do we have a next step we can take before the next time we meet?
16:42:10 <dmsimard> btw I went and looked and ansible 2.10.4 shipped with 'ansible-base>=2.10.3,<2.11',
16:42:23 <acozine> dmsimard: thanks
16:42:51 <acozine> I could do a draft page on "how Ansible versioning works"
16:43:33 <acozine> we could talk to T about how hard it would be to move Scenario Guides into a repo on ansible-collections
16:43:54 <samccann> yeah I think next steps would be driving that decision -to move or not to move files
16:43:58 <acozine> (I mean, moving the files is easy, how hard would it be to publish them from there)
16:44:26 <acozine> sounds good
16:44:30 <samccann> #action samccann to discuss moving scenario guide .rst files to ansible-collections somewhere -w gundalow and abadger1999
16:44:46 <acozine> thanks samccann for driving
16:45:32 <acozine> and thanks cyberpear dericcrago dmsimard lmodemal for joining in
16:45:33 <samccann> one other thing we 'could' do - I don't think there's any reason the 'community guide' has to live in version-specific anything. we could mock up/deepdive on how to publish that as its own docsite for example
16:46:51 <acozine> yes, we can explore generally how much of our current documentation actually needs to be versioned and how versioned and unversioned docs could live together on docs.ansible.com in perfect harmony
16:47:09 <lmodemal> +1
16:47:36 <samccann> #action explore generally how much of our current documentation actually needs to be versioned and how versioned and unversioned docs could live together on docs.ansible.com in perfect harmony
16:47:48 <samccann> anything else before we close out the meeting?
16:48:07 <acozine> not from me
16:48:13 <acozine> I've talked enough ;-)
16:48:30 <lmodemal> nothing from me :)
16:49:24 <samccann> ok thanks everyone! made real progress today!
16:49:28 <samccann> #endmeeting