15:31:38 #startmeeting DaWGs supplemental meeting aka The Great Docsite Split of 2021 15:31:38 Meeting started Thu Dec 3 15:31:38 2020 UTC. 15:31:38 This meeting is logged and archived in a public location. 15:31:38 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:31:38 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:31:38 The meeting name has been set to 'dawgs_supplemental_meeting_aka_the_great_docsite_split_of_2021' 15:31:40 I won't really be around this time unfortunately 15:31:47 felixfontein: we'll miss you 15:32:26 #topic opening chatter 15:32:56 who's available to talk about collection docs vs. core docs? 15:33:00 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 o/ 15:33:25 #chair samccann 15:33:25 Current chairs: acozine samccann 15:33:37 * dericcrago waves 15:33:43 #chair dericcrago 15:33:43 Current chairs: acozine dericcrago samccann 15:34:01 samccann: probably not today, but I'll try tomorrow :) 15:34:15 thanks! 15:34:58 gundalow: dmsimard aminvakil andersson007_ briantist cyberpear madonius persysted tadeboro tremble pinging you as recent participants 15:35:08 o/ 15:35:09 there are seats at the table for everyone 15:35:28 if you are watching this chat and have never participated, you are welcome to join us! 15:35:31 #chair cyberpear 15:35:31 Current chairs: acozine cyberpear dericcrago samccann 15:35:43 Hello o/ 15:35:49 #chair lmodemal 15:35:49 Current chairs: acozine cyberpear dericcrago lmodemal samccann 15:35:57 \o 15:36:02 #chair dmsimard 15:36:02 Current chairs: acozine cyberpear dericcrago dmsimard lmodemal samccann 15:36:46 our current working document is: https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both 15:37:02 thanks everybody for turning up and tuning in! 15:38:36 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 :-) 15:39:08 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 hacked ansible-collections docsite: http://docs.testing.ansible.com/ansible/2.11/ 15:39:47 hacked ansible-core docsite: http://docs.testing.ansible.com/ansible/devel/ 15:39:52 #info draft proposal doc https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both 15:40:08 #info hacked ansible-collections docsite: http://docs.testing.ansible.com/ansible/2.11/ 15:40:22 #info hacked ansible-core docsite: http://docs.testing.ansible.com/ansible/devel/ 15:40:38 # info hacked docsites will disappear without warning in a few weeks 15:40:42 grr 15:40:54 #info hacked docsites will disappear without warning in a few weeks 15:41:09 #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 #topic Which documentation topics/sections will end up where 15:43:03 samccann: on the hacked ansible-collections site on the testing URL, there's a section for `Using and Developing Ansible` 15:43:04 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 yeah it's just a pointer as I figured folks would look for that 15:43:31 So it's an rst page to say 'go here' 15:43:36 ah, so that would be a stub page with links back to the ansible-core docs? 15:43:41 yep 15:45:09 cool 15:46:19 maybe a good next step is to look at the TBD section? 15:46:51 how about we go over the pros/cons first? 15:46:55 sure 15:47:07 #topic pros and cons of splitting the docs 15:47:11 that way people can pipe in on where they see problems with the current split 15:48:17 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 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 can you say more about "is there Ansible package info that shouldn't be on the ansible-core docs"? 15:49:15 Sure 15:49:28 samccann: what about modules and plugins in ansible-core ? 15:49:32 The recent discussions of 'I want my collection to be in Ansible package.. what are the requirements" 15:49:51 and yes dmsimard - that is the other contentious area - ansible.builtin 15:50:05 right, is ansible.builtin considered a collection ? 15:50:06 or core ? 15:50:12 we can either duplicate ansible.builtin, or put a pointer from ansible-collections back to core 15:50:32 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 IIRC the long-term roadmap involves disentangling the ansible.builtin modules from core 15:50:49 For searchability, it should be in ansible-collections 15:51:03 for 'complete docset' it should be in ansible-core. 15:51:48 samccann: +1 for including in ansible-collections 15:51:49 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 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 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 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 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 not an easy problem 15:55:39 but if it doesn't get updated on /devel/ then we upset the developers making those fixes/enhancements etc 15:55:40 that would reflect reality 15:56:03 yeah so thinking it needs to be in both places until it is removed from core 15:56:23 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 yep. but is available to core users.. thus.. needs to live in both places 15:57:33 agreed 15:57:49 though I suppose we could restrict that to the `devel` branch 15:57:59 if we want to de-duplicate for SEO reasons 15:58:26 we're going to need some kind of diagram before long, I think ;-) 15:58:30 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 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 my uneducated guess is that search results will linger with returning ansible-core for builtin plugins until we remove them entirely 16:00:27 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 samccann: probably true 16:01:18 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 that's a good idea 16:02:17 #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 makes sense 16:02:47 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 #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 true 16:03:23 on the other hand, providing links is generally a good idea 16:03:35 Should we move to the next trouble child - guidelines for being included in the Ansible package? 16:03:53 aka the stuff currently being discussed in the community meeting. Where would that doc live eventually? 16:03:59 is that still part of Pros and Cons? 16:04:09 it's a new part of that yeah 16:04:23 okay 16:04:24 though I could just add it to the TBD and we can stick w/ the pros/cons list 16:04:56 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 just added it to tbd so we can continue w/ the existing pros/cons list 16:05:21 but yeah that's the tension 16:05:21 samccann: sounds good 16:05:41 So the next cons - handling latest (and who's latest is latest!) 16:06:17 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 That particular problem goes away if we move all the rst files to say `ansible-collections/docs' repo 16:06:51 to elaborate 16:07:07 currently the latest and cannonical url info is in one sphinx file - conf.py 16:07:48 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 But so long as we have collection rst files in ansible/ansible - we are tied to their release/branching names etc 16:08:51 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 which collection rst files are those ? 16:09:23 scenario guides, network guides mostly 16:10:10 the collection index doesn't actually 'exist' in either repo, it's generated at build time by anstibull 16:10:13 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 could they belong in individual collections and not necessarily in a catchall docs repo ? 16:10:26 some yes, some no 16:10:34 network user guide covers a bunch of collections 16:10:47 AWS likely does for at least two collections today. etc etc 16:11:03 even vmware I think spans 2-3 collections 16:11:32 are those organic leftovers from the various incomplete migrations or are they there on purpose ? 16:11:41 on purpose. 16:11:46 apologies for the simple questions, still learning a lot :D 16:11:57 those are good questions dmsimard 16:12:07 well, the network one is. There are broad categories of information that is applicable to a bunch of individual collections. 16:12:59 so these would be more... "ansible" docs rather than "ansible-core" docs 16:13:00 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 we're also developing content for security applications for Ansible 16:13:07 as in they aren't specific to core 16:13:12 those docs will also be multi-collection 16:13:26 correct, these are specifically NOT core docs. They are tied to one or more set of collections 16:13:57 ok, thanks for clarifying :) 16:15:34 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 the cons ? 16:16:05 it might make them harder to find 16:16:17 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 another con - they would disappear from ansible-core docs likely before we publish Ansible collections docs 16:16:49 for devel only that is 16:17:18 I'm not following harder to find? 16:17:48 they are all there in the proposed Ansible collections doc markup - http://docs.testing.ansible.com/ansible/2.11/index.html 16:17:57 it's a bit hazy even in my mind, tryng to think about challenges 16:18:26 I guess search engines will update the indices pretty quickly 16:18:36 so searches should return the new URLs 16:18:45 yes eventually 16:19:10 but that brings up the other /latest/ problem - When Ansible Collections 3.0.0 releases, it should be marked 'latest' 16:19:11 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 as I think it through, probably not a serious problem 16:19:31 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 well, we could if we really wanted to 16:20:15 #info consider interim stub pages on ansible-core-2.11 to show where all the scenario etc guides have moved to 16:20:38 I mean, we could backport the removal/stub 16:20:47 We can't 16:20:55 no? 16:20:56 because 2.10 today HAS to cover both ansible-core and Ansible the package 16:21:14 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 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 nit: no such thing as ansible-core 2.10 16:23:04 it's either ansible-base 2.10 or ansible-core 2.11 16:23:09 heh 16:23:10 heh yeah theres that too 16:24:00 #info general problems with latest https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both#How-to-handle-latest 16:24:10 #topic handling /latest/ 16:24:20 Since that's what we are discussing now 16:24:30 heh 16:25:04 so what I don't have written there, but should add - Ansible 3.0.0 does NOT get /latest/ at all 16:25:35 as in, we move away from using `latest` altogether for the collections docs? 16:25:36 because it would cause a latest clash with 2.10. 16:25:54 we could bring it back for Ansible 4.0.0 16:25:56 that depends on the "level" we choose for the new docsite 16:26:25 if the new site is `docs.ansible.com/ansible-collections` then it can have its own `latest` 16:26:40 it's still a problem child 16:27:09 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 it depends on ansible-core 2.11... which is also latest. it all makes sense 16:28:13 Same thing for 5.0.0 for a time 16:28:15 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 for posterity, proposed schedule for 3.0 https://hackmd.io/y7BBcweNR3aRVLuMbKkDxw?view 16:29:25 going with that timeline, 3.0 would still ship 2.10 and then flip to 2.11 in 4.0 16:29:45 yeah that's one of the reasons I wanted to jump to 5.0.0 16:29:52 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 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 Yes, it will happen with every release of ansible-core 16:30:36 yep 16:31:10 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 what would you replace latest with ? the version number ? 16:31:29 we 'can' I think still have a cannonical url that gets updated with each Ansible the package release 16:31:32 yes 16:32:30 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 so `latest` means we end up with fewer reddit links to ancient pages that we cannot get rid of 16:33:14 #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 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 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 true 16:35:21 acozine: can you elaborate on older ? 16:35:27 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 the version number of ansible-core will always be behind ansible moving forward 16:36:10 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 right, ok, thanks 16:36:48 #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 I think the intent is to minimize that gap as much as possible fwiw 16:37:03 but this is a specific instance of a more general problem 16:37:34 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 each Ansible version incorporates a specific ansible-base or ansible-core version 16:37:50 not necessarily specific, it's a bound 16:37:58 as in, it's not pinned 16:38:09 yeah so there will always be say a 2-3 week gap between the /latest/ of each when core releases 16:38:13 ah, so it's `2.11 max`? 16:38:18 dmsimard: ^^^ 16:38:49 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 okay, thanks 16:39:39 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 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 #info general feeling so far is to keep /latest/ for both docsites 16:42:00 do we have a next step we can take before the next time we meet? 16:42:10 btw I went and looked and ansible 2.10.4 shipped with 'ansible-base>=2.10.3,<2.11', 16:42:23 dmsimard: thanks 16:42:51 I could do a draft page on "how Ansible versioning works" 16:43:33 we could talk to T about how hard it would be to move Scenario Guides into a repo on ansible-collections 16:43:54 yeah I think next steps would be driving that decision -to move or not to move files 16:43:58 (I mean, moving the files is easy, how hard would it be to publish them from there) 16:44:26 sounds good 16:44:30 #action samccann to discuss moving scenario guide .rst files to ansible-collections somewhere -w gundalow and abadger1999 16:44:46 thanks samccann for driving 16:45:32 and thanks cyberpear dericcrago dmsimard lmodemal for joining in 16:45:33 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 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 +1 16:47:36 #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 anything else before we close out the meeting? 16:48:07 not from me 16:48:13 I've talked enough ;-) 16:48:30 nothing from me :) 16:49:24 ok thanks everyone! made real progress today! 16:49:28 #endmeeting