15:30:40 #startmeeting Documentation Working Group supplemental - docsit split 15:30:40 Meeting started Thu Dec 10 15:30:40 2020 UTC. 15:30:40 This meeting is logged and archived in a public location. 15:30:40 The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:30:40 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:30:40 The meeting name has been set to 'documentation_working_group_supplemental_-_docsit_split' 15:30:51 #topic opening chatter 15:30:52 o/ 15:30:58 Who's around to talk the docs!! 15:31:05 #chair acozine 15:31:05 Current chairs: acozine samccann 15:31:21 partially :) 15:31:28 #chair felixfontein 15:31:28 Current chairs: acozine felixfontein samccann 15:32:43 dericcrago abadger1999 dmsimard gundalo andersson007_ geerlingguy briantist cyberpeaer ? you around to talk docsite split? 15:32:55 * dericcrago waves 15:33:05 relevant documents include https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ with a list of challenges we face, https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both with the potential interim action plan, and https://hackmd.io/Kf2MS6W8SViW6hN9oj6oZA with a possible long-term goal 15:33:15 #chair dericcrago 15:33:15 Current chairs: acozine dericcrago felixfontein samccann 15:33:16 \o 15:33:20 #chair dmsimard 15:33:20 Current chairs: acozine dericcrago dmsimard felixfontein samccann 15:33:29 dang you are fast on the typing today acozine! 15:33:35 Ok let's get started 15:33:48 #topic one Ansible, multiple ansible-cores 15:33:55 I'm just jumping on the administrivia while my morning caffeine hits 15:34:47 We covered this a bit yesterday but to summarize - Nothing stops an Ansible user from updating ansible-core. So an Ansible 3.0.0 fresh install would have ansible-base-2.10 for example. But a user could do and upgrade to ansible-core 2.11 15:35:24 If we want the Ansible the package docsite to have as much info as today's docs.ansible.com/ansible has (aka pretty much everything) - how do we let the reader know the 'core' part of that is actually 2.10? 15:35:45 can we build that into the theme somehow? 15:35:52 or into the version-switcher? 15:35:56 well this is the morning hack I tried - http://docs.testing.ansible.com/ansible/2.11/user_guide/index.html 15:36:06 like "Ansible 3.0.0 powered by ansible-core 2.11"? 15:36:10 oooh! 15:36:11 the version switcher for Ansible package has to stay focused on... ansible package 15:36:57 But we could put that detail 'Ansible 3.0 powered by ansible-base 2.10' in the banner on every page 15:37:21 FWIW there is a WIP for "ansible --version" to display both the ansible-core and ansible versions 15:37:24 https://github.com/ansible/ansible/pull/72287 15:37:43 #info here is a WIP for "ansible --version" to display both the ansible-core and ansible versions https://github.com/ansible/ansible/pull/72287 15:37:46 maybe where the `3.0` shows up, just above the version-switcher itself 15:37:46 thanks! 15:38:51 showing both versions will be very helpful 15:39:08 acozine - I can look, but i'm pretty sure the theme pulls that from the version, so we can't have it 3.0 in one place, and 3.0 powered by core 2.10 in another 15:39:18 ah, okay 15:39:41 bummer, it would be an easy spot to put "stuff that must be visible on every page" 15:39:59 that's the banner. that is on every page 15:40:42 * acozine looks at the hack/mockup again 15:40:51 that PR only makes it more clear that the core version is shown, but it won't show the Ansible version 15:41:19 We would have to get specific with each one to say 'this is the latest docs for Ansible 3.0.0, which includes the ansible-base 2.10 documentation. If your ansible-base version is different, go to xxx' 15:41:51 dang. we definitely need a way to tell both Ansible version and ansible-core/base version 15:42:20 we could add a way to retrieve the ansible version easily to the Ansible package, but apparently core doesn't want to show it 15:42:42 (there was a discussion on this at a core meeting a longer time ago, but I forgot details) 15:42:43 do you know the reasons why they don't want to show it? 15:42:43 felixfontein: what do you mean ? the PR I linked above is intended to do that 15:43:33 dmsimard: well, the code in the PR obviously does not do that 15:43:45 if I'm reading the PR correctly, it shows only the core version 15:43:46 it shows `ansible [core 2.11]` instead of `ansible 2.11` 15:43:48 being the non-coder, reading that PR suggests all it does is add core to the output 15:44:10 yep, "this version we're showing you refers to the ansible-core package", basically 15:44:28 ok well let's action item that one to discuss why we can't also show Ansible version. Cuz we can't solve that here 15:44:29 which is already very good to reduce the general confusion 15:44:47 felixfontein: ah, you're right 15:44:54 #action samccann acozine - ask for a way to show the Ansible version along with core version installed 15:45:23 worst-case, we fall back on `pip show ansible` 15:45:32 so back to the docs side of things - if we add a banner that states the Ansible and core versions that the doc shows, is that enough? 15:46:14 showing ansible version in `ansible --version`: 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 15:46:25 #info can use a combination of ansible --version (to show core version once the pr is merged) and pip show ansible for the Ansible version 15:46:44 thanks felixfontein. we'll look at that after this meeting 15:46:50 (the discussion starts at `#topic https://github.com/felixfontein` in that log) 15:46:54 I don't know how to present this, but in my mind the ansible versions 3.0, 3.1, etc, would just be a symlink to the ansible-core 2.11 version 15:47:17 we'll definitely need a page or paragraph somewhere that says "here's how you tell which versions you have installed" 15:47:44 dericcrago - take a look at the hack - http://docs.testing.ansible.com/ansible/2.11/user_guide/index.html 15:48:04 acozine: +1 for that! 15:48:10 So we would 'magically' pull stable-2.10 docs into the Ansible 3.0 docsite and 'magically' add the 2.10 into the title. 15:48:16 (yeah lots of magic right now). 15:48:40 #info will need a page or paragraph somewhere that says "here's how you tell which versions you have installed" 15:48:50 maybe the ansible package could contain a CLI tool `ansible-version` whose sole purpose is that :) 15:48:52 yeah there is an issue already for that that I think lmodemal is assigned 15:49:37 sorry an issue for documenting how to find the different versions 15:49:57 dericcrago: that's an interesting idea - basically the URLs for docs.a.c/ansible/3.x would symlink to the same pages in docs.a.c/ansible-core/2.10? 15:50:25 felixfontein: Heh. 15:50:36 then the collection and plugin pages would be add-ons, in a way 15:50:43 thanks samccann, so if I'm understanding correctly, if I know my ansible version I'll end up at the right ansible-core page, but how easy would it be to end up at the right ansible-core page without needing to know the ansible version 15:50:50 #chair abadger1999 15:50:50 Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein samccann 15:51:15 dericcrago: But then you won't end up with the correct ansible collection pages? 15:51:33 derricrago - you would look at the ansible-core docsite (as separate/new docsite just for core) 15:51:41 I'm thinking if I rolled my own, ala carte style 15:51:41 dericcrago: we will publish the ansible-core docs under separate URLs so folks can find specific core versions 15:51:56 ok 15:52:27 so the same content will show up at docs.a.c/ansible/3.0/user_guide/playbooks_tags.html and docs.a.c/ansible-core/2.10/user_guide/playbooks_tags.html 15:52:39 ah, as an addon, as acozine says.... Yeah. If you start thinking of them as separate documents... here are the framework docs for ansible-core and the plugin docs for ansible-X, ansible-Y, ansible-Z then that could work 15:52:46 I'm not clear how the symlinks between ansible and ansible-core would work? We wouldn't want the reader to switch docsites so to speak 15:53:00 whether we could do that using symlinks, I'm not sure 15:53:26 as samccann says, the links would have to be smart enough to keep the user on that `/ansible/3.0` trunk 15:53:43 or on the `/ansible-core/2.11` trunk if that's where they started 15:53:56 I think SEO was raised as a possible issue if the content was exactly the same? If so, symlinks of the entire tree won't work. 15:54:28 I heard before that the same content shouldn't be available under two different URLs for SEO reasons 15:54:28 I don't know if there's a specific file in the theme or a specific page that must be real (and different) and then the rest of the tree can be symlinks, though. 15:54:31 for SEO - i think the solution is that ansible-core docs do not use /latest/ or cannonical url anymore. They are strictly versioned 15:54:53 Where is canonical url specified? 15:54:59 So, as I understand it (what little i do) - that's the point of cannonical url - to say, yeah we have multiple copies, but THIS is the important one 15:55:10 abadger1999 - its in the conf.py for the sphinx theme 15:55:47 Okay, so probably we can't use symlinks but generating two versions of the docsite from the same rst and different conf.py files would work. 15:55:47 IF we decide this is the way to go, I can ask our internal SEO expert for advice 15:55:59 yeah that's what I was thinking 15:56:25 abadger1999: https://github.com/ansible/ansible/blob/3e9943bc5e7a9cd393757aa8100d7fed80bd316e/docs/docsite/rst/conf.py#L138 15:56:33 So, are we at a point where we can VOTE on some of this? 15:57:16 #info symlinks likely will be bad for SEO but generating two versions of the docsite from the same sources could work (along with other limitations) 15:57:26 like that we agree on repeating the user guide on both docsites? 15:57:41 I think so, yeah 15:57:44 or that docs.ansible.com/ansible stays for the Ansible package docs and ansible-core moves to a new site? 15:58:08 #info Known things that would have to change to maintain good SEO with duplicate content are the /latest/ url and canonical url which is specified in the conf.py 15:58:31 VOTE: We will duplicate user guide on Ansible docs and ansible-core docs 15:58:43 (with appropriate SEO optimizations) 15:58:47 heh 15:58:49 +1 15:58:53 +1 15:59:06 +1 15:59:16 +1 15:59:51 #chair 15:59:51 Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein samccann 15:59:51 +0.5 (Coming in late so I don't want to weigh in too heavily but I can see no glaring flaws) 16:00:31 ok gonna call it 16:00:50 4 in favor, one a half, and two not voting. 16:01:10 #agreed We will duplicate user guide on Ansible docs and ansible-core docs with appropriate SEO optimizations 16:01:32 #action samccann to ask internal SEO expert how to handle duplicat content - is cannonical url enough? 16:01:39 next topic 16:01:48 #topic moving ansible-core docs to a new docsite 16:02:00 We haven't spoken about this so I figure we should officially. 16:02:23 if we're duplicating the user guide, we have to have somewhere to duplicate it TO 16:02:42 The TL;DR; - our product guy inhouse is in favor of keeping docs.ansible.com/ansible for Ansible the package and creating a new docsite for ansible-core 16:03:43 I think this arrangement makes sense, it follows the Ansible tradition of "make easy things easy and harder things possible" 16:03:44 So the question is - do we agree with that assessment? Keeping in mind that searches etc will all go to Ansible the Package. And ansible-core becomes the 'special case' so to speak. 16:04:08 I feel like we need core people to pipe in on this... 16:04:34 folks who want to pick-and-mix collections with a specific ansible-core version are already working harder than those who use the pre-packaged Ansible 16:04:36 sivel - any chance you are around? 16:04:51 they can take that extra step of finding the right versions in the docs 16:05:22 I think sivel's on PTO 16:05:27 ah ok. 16:05:45 #action samccann to discuss ansible-core having its own docsite w/ core team 16:06:00 anyone else have thoughts/opinions on this one? 16:07:29 ok gonna move on to the next topic then 16:07:51 #topic ansible-core docs with no collection index 16:07:57 this one has two parts 16:08:18 part 1 - ansible-core would not have any of the scenario guides/network guides etc. so you could say it's 16:08:20 incomplete 16:08:47 whereas the Ansible docs would be complete. This came up in some other discussions so wanted to see if folks are okay with that? feel it's wrong, etc 16:09:47 abadger1999 did you want to add anything else to that? 16:10:10 It doesn't feel right to me but the argument was made that we should wait for personas to land and then we should revisit how we can change this. I'm okay with that timeline. 16:10:22 ok cool 16:10:29 incomplete as in needing to go to the other docsite for other things ? 16:10:34 yes 16:10:48 and if you search on ansible-core for 'network modules' for example, you'd get nothing 16:11:02 until/unless we have some kind of site-level search that goes across the docsites 16:11:07 whereas the ansible docs would contain the ansible-core docs ? 16:11:11 ansible-core docs being about ansible-core and ansible docs being about the full experience (collections, guides, etc) makes sense to me 16:11:11 yes 16:11:18 dmsimard: Yes. and the reason going to a different docsite is problematic is that navigation elements won't be able to bring you back. 16:11:46 (user needs to use browser back or an explicit link in the text of the page would need to send you to the ansible-core docsite) 16:12:03 makes sense 16:12:11 it's not ideal but I don't see a better solution for now 16:12:13 samccann: oh.... site-level search will be more tricky too. 16:12:32 as you won't want a search in ansible to send you to the content in ansible-core, for instance. 16:12:46 (But again... this is stuff that's further out on the timeline so we can revisit then) 16:12:50 yep.. 16:12:59 #info while it 16:13:04 #undo 16:13:04 Removing item from minutes: INFO by samccann at 16:12:59 : while it 16:13:07 dang typo 16:13:10 heh 16:13:29 existing site search isn't the greatest, to say the least 16:13:58 #info while it is not ideal that you can't find anything about networking/cloud/security on the ansible-core docsite, this is an short-term fix until we get to a docsite based on personas and a better way to get between all the information 16:14:18 ok moving on 16:14:53 #topic moving non-plugin collections docs to other repo(s) 16:15:06 #info see the section here for an overview - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ 16:15:27 #info and see here for some real detail - https://hackmd.io/pPeMLaFYSt2W8RAqm-ZkXA 16:16:08 The gist of it is - these scenario guides are mostly tied to a collection (though some might be tied to a group of collections). They don't 'version' with ansible-core anymore, yet they exist in the ansible/ansible (aka ansible-core) repo 16:16:12 samccann: note also.... I think the (previous) topic encompasses whether or not you can find ansible.builtin documentation on the ansible-core docsite.... 16:16:31 oh dang yes! that' was the part two!!! 16:16:35 quick topic change 16:16:49 #topic where do we publish ansible.builtin docs 16:17:07 Going off of the "collection docs are an addon", the docs for modules and plugins in ansible.builtin would end up in that addon. 16:17:08 So this ties into ansible-core as its own docsite again. Sorry 16:17:36 /13 16:17:47 sorry ^^ 16:17:54 So the question is - do we publish ansible.bultin on BOTH docsites? on just Ansible? 16:18:21 today, it IS part of core, so I'd lean toward publishing on both. So a strictly core user has all the info they need on ansible-core docsite 16:18:27 I think we can modify the build process to build it for the ansible-core docsite but it will be different in that way (which means we'll have to figure out how to link it from both the ansible and ansible-core rst files) 16:18:42 'some day' it may be separated into its own collectin, so once it's not in core, it's not in core docs imo 16:19:03 can you elaborate abadger1999? I'm not following 16:19:04 samccann: sorry, I'm here, but was occupied a few minutes ago 16:19:15 good timing sivel 16:19:28 The prior conversation - 16:19:53 We are considering ansible-core to be its own docsite. So docs.ansible.com/ansible would stay as the Ansible the package docsite, and core would get a new one. 16:20:20 that's basically what we wanted to catch your attention on since it's come up recently and haven't had a chance to see what core folks think 16:20:43 What does that realistically mean? 16:21:15 I'd imagine it would be hard to separate that since ansible-core provides the mechanism for which everything else operates 16:21:32 we will duplicate the core content 16:21:34 it means that for example, readers googling 'how do I do a playbook' will get docs.ansible.com/ansible results, and thus be looking at a docsite that is Ansible the package 16:21:59 as in our search optimization would focus on Ansible, not ansible-core. That said, ansible-core user guide would be duplicated on both docsites 16:22:00 I think I've been assuming that /ansible would forever be ansible-core, and collection docs would eventually go away 16:22:28 so everything we have now will still appear as docs.a.c/ansible/#.# and we'll add a section for docs.a.c/ansible-core/#.# 16:22:31 but I haven't been paying attention recently 16:22:34 i'll be honest- that was my original proposal. But feedback, including PM, was in favor of keeping the current docsite for Ansible 16:23:15 (Clarification request: PM == Project Manager, not Private Message, right?) 16:23:26 it means the internal Power That Be, yes 16:23:30 until we have some other, discoverable way for users to find/view module docs on the web, collection docs can't go away 16:23:30 16:23:58 What benefit do we get if we have a separate ansible-core site? I'm unsure how many would use it. ButI'm having problems conceptualizing what changes might make it useful 16:24:22 The biggest problem we have sivel is core has different versions than Ansible going forward 16:24:49 so we'll have Ansible 3.x based on ansible-core 2.10 16:24:52 So while 99% of the user guide for 2.10 and 2.11 will be the ssame, the Ansible 3.0.0 user needs 2.10, not 2.11 for example 16:24:56 then we'll have ansible-core 2.11 16:25:25 then we'll have Ansible 4.x and 5.x etc. based on ansible-core 2.11 16:26:15 Ok, yeah, I suppose I can see that problem. I appreciate the heads up. 16:26:18 So we need 'older docs' so to speak to go with Ansible, and the newer core docs to be on their own, for those users who upgrade just core 16:26:36 I'll try not to distract, since I'm not sure that was your goal in pinging me ;) 16:26:50 I think traffic to a separate ansible-core site will be low, but it gives users a way to know what's in a specific core version if they are "rolling their own" 16:26:54 well we wanted a core opinion so to speak :-) 16:27:21 My opinion, without having had time to think about this, is it's going to be massively confusing, probably more than now 16:27:39 but I also look at it from a different direction 16:27:46 as I am not an "ansible" consumer 16:28:13 it reflects a confusing situation 16:28:16 and RH customers are also not ansible consumers 16:28:23 can you elaborate? 16:29:02 samccann: Do we want to run any of the other proposals we discarded by sivel or do we want to leave those in the discard pile as they are infeasible for other reasons? 16:29:23 "ansible" is a community distribution, and RH customers, unless something has recently changed, will not have access through RH channels to what we previously called ACD 16:29:39 abadger1999 - I think in general we need a 'combined' meeeting, w/ us, core, maybe those Powers that Be to hash it all out 16:29:40 RH customers will get ansible-core, and will not consume ansible 16:30:08 At least those of the platform 16:30:32 sivel - there is a longer term plan for RH customers and what they get.. those would be on access.redhat.com. 16:30:49 which is not to say that solves everything.. it's all just a big fuzzy notion right now. 16:30:53 yeah, I get that too 16:31:13 just concerned we might taking confusing up a notch for a short time with the current plan 16:31:35 it's confusing now, it'll become confusing++ :) 16:31:41 heh 16:31:45 but I don't have better solutions fwiw 16:31:52 ok to take a step back - we KNOW come jan/feb that Ansible3.0 releases, and depends on base-2.10 16:32:17 We 'could' just take over the existing docsite and publish it as just that. 16:32:26 Yeah, and ansible-core releases in April 16:32:34 Question.... would you feel better if 2.11 wasn't documented on the website until ansible-34.0 comes out (probably about a month after 2.11)? 16:32:46 The impact would be when core releases, it would have NO docs until Ansible 4.0.0 releases and includes core-2.11 16:32:48 What if the version was just referenced as 3.0/2.10 everywhere? 16:33:04 (that's an easy solution to the confusion factor... but I didn't like it because then there's no docs for the latest ansible-core release on the web) 16:33:21 yes we could do that. The impact is just as toshio said, 2.11 core gets not docs until Ansible. 4.0.0 picks it up 16:33:24 X/2.11 ;) 16:34:00 well, would it be 3.x/2.10 in that case? 16:34:08 samccann: being clear about ramifications, this would also encompass /ansible/devel/ ? 16:34:09 my nickel guess is that scenario would stick around for a year or more. 16:34:23 Or could we leave that as documenting 2.11? 16:34:44 abadger1999 - off the top of my head, I'd think /devel/ stays in sync with core, yes 16:34:59 I mean we could use the same site, and just have 3.0, 2.10, and 2.11 as version drop downs. 16:35:10 I'm coming into this a little cold, so I don't know what has been discussed 16:35:15 so I might be bringing up old ideas 16:35:18 oooo 16:35:20 ooooo 16:35:22 like, literally `3.X/2.10` & `next/2.11`? 16:35:26 hadn't thought of that one sivel 16:36:03 is having a `2.11` "ahead" of a `3.0` less confusing than separating the two streams? 16:36:15 acozine: I imagine we'd have to prefix them maybe 16:36:20 not have just a raw version number 16:36:21 (This development cycle [leading to ansible-3.0.0 and ansible-core-2.11 is where it will be most confusing as right now /ansible/devel/ does not signify ansible-3.0.0, which is the ansible package in development]) 16:36:26 I don't think that works. 16:36:41 but maybe some combo of what I have mentioned and what dericcrago just mentioned 16:36:41 #info we need to track ansible version as 3.X since it will be one docset to cover 3.0, 3.1, etc (aka semver) 16:36:44 because one day ansible-core may want to use 3.0. 16:37:06 so the versions might need to be `ansible-3.0` and `ansible-core-3.0` for example 16:37:13 and then we'll have a conflict with the directory tree and possibly the version switcher if it happens too soon. 16:37:24 16:37:37 just some ideas 16:37:38 yeah, putting the package into the version might work. 16:38:06 or abstract that away, and the version switcher switches subdirs 16:38:08 the version selector code right now is on the 'fragile' side because.. .frankly, I just hacked it from someone's old sphinx theme code that was rejected 16:38:19 but a smarter coder could probably make ^^ work 16:38:34 URLs won't look right, I guess, though? 16:39:08 But that feels like a lesser issue than the duplicated docsite. 16:39:14 if we can agree that the "version" section of the URL will always be the Ansible version and never the core version, that might work 16:39:27 #info can we have `ansible-3.x', `ansible-core-3.0`, etc in the version dropdowns so we have one docsite with both sets of info? 16:39:41 `ansible-3.X_ansible-base-2.10` and `ansible-NEXT_ansible-core-2.11` 16:39:51 Yeah, I think my vote is to see what we can do with a version dropdown, instead of duplicated sites 16:40:05 in other words, docs.a.c/ansible/3.0 is only for Ansible 3.0, and when we get to ansible-core 3.0 the URL will be something like docs.a.c/ansible/15.0 16:40:10 that would likely break the existing them dericcrago - we con't have a lot of 'space' in the version selector right now for long words 16:40:32 s/con't/can't/g 16:40:34 samccann: I'm sure we can get some help with the dropdown if we need 16:40:41 we have a lot of people that do web dev in our org 16:41:01 Hmm.... this is probably minor, but what will the version dropdown for ansible-core-2.10 go to? /2.10/ or /3.0 ? 16:41:08 yeah I think we have some flexibility there, but then we run into the left-hand-navigation bar itself is limited in size. 16:41:21 abadger1999: why not include the prefix in the URL? 16:41:32 abadger1999 i think 2.10 stays just 2.10 as it covers both now 16:41:33 sivel: example? 16:41:36 sivel: acozine is saying not to do that. 16:41:47 then we add 3.x, then core-2.11 etc 16:41:49 /ansible/ansible-core-2.10/user_guide... 16:42:03 I mean it could be shortened to core also 16:42:13 /ansible/core-2.11/whatever... 16:42:31 sivel - not sure how the navigation in the sphinx theme would handle all that. It's currently all published to one url 16:42:43 but `core-2.11` will cover multiple different versions of Ansible, probably 3.0, 4.0, maybe 5.0, right? 16:43:04 so we have /ansible/2.10/, /ansible/3.0.0/, /ansible/4.0.0/, /ansible/base-2.10/, /ansible/core-2.11/, ...? 16:43:15 felixfontein: that's basically my thought 16:43:15 sorry: so we have /ansible/2.10/, /ansible/3/, /ansible/4/, /ansible/base-2.10/, /ansible/core-2.11/, ...? 16:43:26 yeah ^^ is what I'm not sure sphinx theme can handle 16:43:32 actually... I think the question still exists even if the url contains the prefix because the content would still either reflect ansible-2.10 or ansible-3.0 16:43:40 for me /anisble/core-2.11/ is pretty much that's equivalent to /ansible-core/2.10/ 16:43:43 gna 16:43:46 can't type today :) 16:43:54 for me /anisble/core-2.11/ is pretty equivalent to /ansible-core/2.11/ 16:44:06 if we do ^^^ isn't that basically a docsite split? the content at /ansible/3/ and /ansible/core-2.11 is the same 16:44:37 acozine: except that /ansible/3/ also has the scenario guides and the collection plugin docs 16:44:42 acozine: I think the difference would be full docsite under /ansible/ vs partial docsite under /ansible-core/ 16:44:48 felixfontein: yeah, which was my other comment, that the version switcher abstracts away the subdir change, so everyone can go to `/ansible` and then still get their version of the docs 16:44:54 what felixfontein said. 16:44:58 right, so we're back to the original plan, just with different URLs 16:45:06 yeah... 16:45:41 hmm, sounds like a good plan :) 16:46:02 I think I'm roughly fine with that as we've been talking, if we can find a way to still get everything into a single consolidated version dropdown 16:46:07 so i think the only difference is we are trying to 'hide' that it's two urls/two docsites by having all the versions available in the version switcher 16:46:10 sivel has a good point there.... maybe the UI is better for users if it's seen as part of the version switcher rather than as having to type in a different url. 16:46:11 to me, that feels even more confusing - what happens if I'm on a collections page in 3.0 and i select core-2.11? 16:46:50 then it's the same as if you were on /latest/ and you select say 2.8 - you go 'someplace else' 16:46:59 maybe we should engage the team helping with platform UX? 16:47:07 acozine: that's the main downside... that won't work, resp. you could get redirected to /ansible/core-2.11/ 16:47:08 the difficulty tho - is it's likely a redirect to the top of core 16:47:45 you can still 'undo' the redirect by using your browser's back button 16:47:46 sivel - we don't have much time. I can't envision us getting a big ux change in place by end of Jan when we need all this 16:48:00 for 98% of pages if I'm on latest and i pick 2.8, I get the same content but for the earlier version 16:48:29 Hmmm...... acozine so two possibilities: (1) core-2.11 can't exist until ansible-4.0 is released (2) we enhance the docs build process to build devel and core-2.11 collection docs. 16:48:32 yeah so with 3.0 vs core-2.11 you get 404 A LOT 16:48:44 samccann: one thing I always try to tell people in regards to our development, is we don't have to get 100% of the way there. If the version switcher ends up in a 404, then so be it, but I think it's still better UX for the version switcher to be the "entry point" 16:48:58 we can improve it as we go 16:49:31 I think I've made my concerns at least somewhat clear though :) 16:49:42 yeah, thanks sivel 16:49:53 i think 404 in that case would be too big of a problem for end users. 16:50:30 404 not found, if you were viewing collection docs, and selected an ansible-core version, these docs are unavailable for the version you selected. Click to go "home" 16:50:34 we could potentially put in redirect(s) but it would still end up at the top of some section. 16:50:53 Just add some helpful wording like ^ 16:50:59 I'd rather core-2.11 didn't exist until ansible-4.0 if those were the two choices. (But option 2 [for devel] is something I've wanted to do.... if this forces the implementation of that feature then it's not a big problem.) 16:51:11 the bigger concern i see is that it's harder to understand that 4.0 includes 2.11 16:51:26 can you elaborate? 16:51:30 abadger1999: what is 4.0 timeframe? We'll need 2.11 docs by end of May for the platform 16:51:32 if we put that in the banner 16:52:06 as a user, when I see the version dropdown, I think "oh these are all different versions of the same thing" 16:52:28 Yeah, we probably definitely need docs that indicate what -core version is utilized, and provide a link to the -core version standalone docs too 16:52:42 so when I see 2.11 and 3.0 I think these are a maintenance version and a new-features version 16:52:53 when it's exactly the reverse 16:53:21 sivel: so you're on board with having a separate docsite for core docs? 16:53:30 sivel: The roadmap for 4.0 is extremely tentative but this is what I've asked people to think about: https://hackmd.io/y7BBcweNR3aRVLuMbKkDxw#Proposed-Extremely-Tentative-Schedule-for-Ansible-400 16:53:38 "core version standalone docs"? 16:53:55 (AN) 2021-05-18 ansible-4.0.0 release 16:53:59 acozine: I can be as long as the non-core docs still have links to the "core version standalone docs" 16:54:18 Although.... I think it would be possible to start building the docsite for that once we cut the first alpha? 16:54:28 Hiding them in another URL that isn't directly exposed from /ansible/ will probably be problematic in my view 16:54:34 I don't remember the code for that off the top of my head. 16:54:47 which is why I was asking for the version switcher to include versions from both sites 16:54:54 "Ansible 4.0.0 is ansible-core 2.11 with a selection of collections. This site shows the combined documentation. To see only the ansible-core 2.11 documentation, click here."? 16:55:00 okay, thanks 16:55:22 felixfontein: yeah, something like that 16:55:40 acozine, samccann Oh... another thing.... this is all temporary, right? Once personas arrive, we're going to redo this? Does that affect whether we want it to show up i nthe version switcher now? (would we remove it from the version switcher later?) 16:55:57 abadger1999: everything is temporary 16:56:01 ;-) 16:56:02 heh.. so ...zen 16:56:26 hah :-) 16:56:45 sivel: I don't think there are standalone docs in this idea of the plan. 16:56:47 sivel felixfontein - this sounds like we are back to the original proposal. See - http://docs.testing.ansible.com/ansible/2.11/user_guide/index.html 16:57:12 core-2.10 docs are equivalent to (one of) ansible-2.10 or ansible-3.0 docs. 16:57:26 (ignore the version in the url) - but basically we pull in the 2.10 user guide from core, give the user some info of where to find say core-2.11 standalone etc. 16:57:34 abadger1999: I'm slightly confused by trying to track the various ideas and where we are :) 16:58:05 two docsites, but with appropriate info/links to help the user. And the version switcher stays the same as it is today (only versions on that docsite, not for the 'other' docsite) 16:58:13 sivel: heh that's bad considering we're trying to construct something around your idea ;-) 16:59:20 abadger1999: in the end all I can do is give feedback, and hope it can be put to something useful. Otherwise, I tried :) 16:59:33 but we should try to distill this down, and get a doc out to more people than just me 17:00:46 alright... so I think where we're at is acozine is proposing going back to the original idea of separate /ansible/ and /ansible-core/ docsites [where ansible-core has less information]. And sivel has said that as long as there's links between the /ansible/ and /ansible-core/ docs and vice versa. 17:01:28 acozine: ^ Does that sound right? 17:01:36 is /ansible/core-xxx/ no longer in the game? 17:01:37 we can mock this ^^ up a bit better and then have a wider meeting on it all to walk through the experience 17:01:40 I think so, yeah 17:01:48 thank you all 17:01:55 thanks sivel 17:01:58 felixfontein: yeah, in terms of what acozine is proposing, yes. 17:02:09 providing good links to the core docs will be vital 17:03:02 sivel: the part 2 is also something you'll want to weigh in on. 17:03:09 #action samccann to create better mockups of separate /ansible/ vs /ansible-core docsites for review 17:03:10 what we really need is a dual-choice thing 17:03:16 like geranimals for docs 17:03:22 acozine that is a page up, on docs.ansible.com 17:03:37 choose core or Ansible 17:03:43 abadger1999: 2nd part being unified links between the 2? 17:03:54 pick your core version, then select your Ansible package on top of that or select "none" for roll-your-own 17:03:54 part 2 sivel - where do we document ansible.builtin 17:04:15 samccann: yeah, that's true 17:04:18 (unless abadger1999 had a different part 2 in mind?) 17:04:55 samccann: it should definitely be in /ansible-core, and since /ansible-core is duplicated into /ansible it should be both 17:04:57 samccann: yeah, that's right 17:05:11 -1 to definitely. 17:05:32 heh, abadger1999 what's your concern? 17:05:35 Heh, I was going to ask if we're ready to change the topic but I see that's already the topic ;-) 17:05:38 So... 17:06:03 if ansible.builtin docs are not with ansible-core, that's both misleading, and confusing 17:06:24 The way I see it, if we're attempting to encode support into the split between two docsites, then we need to document ansible.builtin in the ansible-core docs as they're supported as part of ansible-core. 17:06:54 sivel: at one time the logn-term roadmap included removing the builtin modules over time, is that still on the roadmap? 17:07:01 If we want end users to have a good experience with the organization of the docs then we need to put the docs into the plugin docs. 17:07:03 acozine: no 17:07:47 ansible-core will continue to always have modules plugins, we have no plans to remove them 17:07:53 At the moment, I think we want both (maybe when access.rh.c becomes the differentiator for supported vs unsupported, that equation changes)... so I would propose we build them at both places. 17:08:10 agreed, they belong in both sets of docs 17:08:32 agree 17:08:34 we can't leave them out of the core docs, esp. if they are staying in core for hte long haul 17:08:34 acozine: And to be clear... it's not just "in both sets of docs" as in in both /ansible/ and in /ansible-core/ 17:08:49 I think thats what I said, but maybe that "-1 to definitely" wasn't directed at my comment 17:09:06 It's also.... as part of the structure of each of those sites. 17:09:38 how would folks feel about doing for the ansible-core docs what we do now for the devel docs? 17:09:41 ie: /ansible/3.0/collections/ansible/builtin/ and /ansible-core/2.11/plugins/ansible/builtin 17:10:00 (or whereever we end up placing the second one) 17:10:06 https://docs.ansible.com/ansible/devel/collections/index.html 17:10:13 abadger1999: I think I'd like that, but I wouldn't kick and scream if we couldn't do that 17:10:36 back to my prior statement, we can iterate, and improve 17:10:39 (to be clear, we do that now for devel "by default", not because we thought it was a great solution) 17:11:49 A problem that will have to be addressed with doing this is how to tie these into the rest of the site(s). will /ansible-core/2.11/collections/ansible/builtin/ not exist and /ansible/3.0/plugins/ansible/builtin/ not exist either? 17:12:05 having those modules in two places within the `/3.0/` section REALLY complicates SEO 17:12:19 then we'd have the same content in 3 locations, two of which are in the same section 17:13:02 If those are linked from static indexes, then we'll need to link across sites and tell the user that they're leaving one set of docs for the other. 17:13:51 I guess this is complicated by some collection docs using M(ansible.builtin.xxx) to reference core modules 17:14:07 (since the rst building the static stuff will be the same between ansible and ansible-core) 17:14:28 yeah, that's why I was thinking of leaving the builtin modules in `/collections/` in both sections 17:14:29 felixfontein: ah... yeah, so /ansible-core/2.11/collections/ansible/builtin will have to exist. 17:14:50 abadger1999: isn't it more that /ansible/3/collections/ansible/builtin needs to exist for that to work? 17:15:09 abadger1999: because in the HTML tables, I guess M(...) resolves to something using relative links? 17:15:15 felixfontein: oh, you said collection docs. Yes, that's true. 17:15:16 is the problem that which intersphinx link M() would use? 17:15:29 can address the SEO issues 17:15:40 as in core M() should go to core, and Ansible M() should go to ansible? 17:15:41 samccann: intersphinx won't work for M(...) in options 17:16:00 samccann: we'd need special code to handle ansible.builtin differently 17:16:10 (of course that's possible, just more messy) 17:16:21 felixfontein: it will also affect ansible-core docs that link to the collection docs. 17:16:22 can someone attempt to summarize the problems here with a sprinkling of infos? 17:16:36 abadger1999: does that actually happen? 17:16:38 can we build the least-changed version of this idea out to the testing site, then try out the user experience to see how it feels? 17:16:56 felixfontein: Maybe... The bigger question woul be... do we want it to? 17:17:16 If we don't want it to, then we can edit the source o remove the links. 17:17:31 abadger1999: it does, like ping references M(ansible.windows.win_ping) and M(ansible.netcommon.net_ping) (though not in options) 17:17:49 by "least-changed" I mean treating the ansible-core content the way we treat devel today, with the builtin modules under collections 17:17:57 and the ping example shows that we probably want it 17:18:06 acozine yes I can do that 17:18:48 acozine: yes-ish... what I'm bringing up here is that there are new problems relative to what we deal with in devel. 17:19:09 because we're going to want to link across the docsites. 17:19:28 but we're going to be building from a single source. 17:20:03 is this at all solved if we run the Ansible build from a different repo? (as in all new conf.py, all new intersphinx links?) 17:20:23 abadger1999: maybe we need to make antsibull more intelligent, so it does consider which collections it is building docs for when creating M(...) links - like reference to the collection on galaxy if the collection is not included in the current docs build 17:20:30 so core has intersphinx to core and then Ansible, and Ansible has intersphinx only to Ansible? 17:20:33 I think the separate conf.py is mandatory. We can generate that in the builder if we need to. 17:20:45 intersphinx might help with the technical aspect. 17:21:13 abadger1999: but only for M(...) that resolves to RST, not for M(...) that resolves to HTML 17:21:15 you'll still have to deal with writing one explanatory text that works for both ansible and ansible-core docsites, though. 17:21:31 #info we will need separate conf.py to do all this... tho might be done w/ builder instead of different repos. Intersphinx might help with M() between the docsites some 17:21:36 samccann: because it's a single source, I think we'd need core and ansible to use the same intersphinx. 17:22:24 and in the ping => ansible.windows.win_ping example, perhaps we'd need to change that to an intersphinx link. 17:22:26 I guess the intersphinx files need a different order depending on which docsite is built, to prefer local links (or does intersphinx already does that automatically?) 17:22:36 * acozine AFK 2 mins 17:23:25 ok let me try to boil this down a bit 17:23:26 Oh.... you're thinking of relying on implicit intersphinx? 17:23:37 * acozine back 17:23:40 our 'worst case' scenario is we turn off all M() for core docs? 17:23:58 felixfontein: if so, intersphinx will prefer links which are resolved locally before looking in its intersphinx catalogs. 17:24:07 As in no linking. Does that remove the problems y'all are discussing? 17:24:11 abadger1999: ok, in that case 'everything is good' :) 17:24:32 samccann: no linking kind of sucks, but it does solve the problem :) 17:24:45 I was thinking of explicit intersphinx, though :ansible_3_0:'ansible.builtin.win_ping' 17:24:47 ok just wanted to be sure I wasn't missing some other wrinkle 17:25:40 I seldom use implicit intersphinx because it feels easy to overwrite the anchors but maybe it will work. 17:25:52 (I didn't even know implict was a thing until earlier htis year) 17:26:19 I didn't know explicit was a thing until today :) 17:26:27 heh 17:26:34 ok we are 2 hrs into a 1 hr meeting 17:26:37 ;-) 17:27:01 do we have some next steps? 17:27:03 what is critical that we discuss next? 17:28:15 samccann: feels like normal already ;) 17:28:16 critical outcome from where I sit is at least one action we can take so that next week we at least start at a new place (and with luck end at a new place also) 17:29:02 samccann: So an example of the content problems I'm talking about: on the /ansible-core/2.11/collections/index.rst you'll need something that says the equivalent of "If you are reading this as part of the ansible-core docs (check the URL), then there are more plugins available to you in the ansible package. Go to that page here: /ansible/4.0/collections/index.html. If you are reading this on the ansible docs, but you are 17:29:02 only using ansible-core then the only plugins available to you out of the box are those in ansible.builtin" 17:29:52 #info need something on ansible-core collection index to say 'go to ansible for much more' 17:30:19 I could draft some text for that, and also a page or at least an FAQ entry about "what are all these versions?" 17:30:22 anywhere where we're interfacing between static and dynamic docs will have that issue 17:30:24 So if I were to summarize today - we are still with two docsites... ansible.builtin on both.. .we have some linking/intersphinx to fix 17:31:18 abadger1999 - static to dynamic would work fine on Ansible, but not on ansible-core, right? 17:31:29 samccann: because we're doing single source, I think it shows up on both ansible ansible-core? 17:31:54 Maybe we can put all this text on the dynami pages. 17:32:28 ie: collections/index.html is generated by antsibull-docs so we can template different things depending on whether we're building for ansible or ansible-core. 17:32:32 abadger1999 so because the user guide is single source on both docsites, this problem occurs for static to dynamic? 17:34:01 Ahhh... yeah, it can..... Maybe we can ignore the issue in those guides? 9as in, the user guides will always assume that you have ansible installed, not just ansible-core)? 17:34:55 yeah I think we'll have to make compromises like that for sure 17:35:51 but back to next steps. What can we get for mockups for next week? is that an important next step, or solve some of these linking problems? or...??? not sure where to go next and frankly, it's the last meeting of the year and come January, we have to do some actual implementation of 'whatever' to make the deadlines 17:37:31 I think we all agree that the core-2.11 docs need to appear twice, once as part of the Ansible version that relies on core-2.11 and once as a standalone thing 17:38:34 +1 17:38:36 we also need to socialize all this w/ the core team and TPTB 17:38:55 some prefer all versions to appear in a single dropdown, others two different dropdowns - is there one of those ideas that would be easier to implement as a test case? 17:39:26 two different is easy cuz I've done it already multiple times in the past month :-) 17:39:46 versions in thedropdown... maybe. I can try 17:39:48 heh 17:40:34 have you built it out with multiple versions on the /ansible/ side already? 17:40:45 dunno what you mean 17:40:53 as in a pretend 3.0 and 4.0? 17:41:34 I may be getting muddled, I'm trying to get to "can we test the sphinx links today on the testing site?" 17:41:53 and "can we try out moving back and forth from one site to another?" 17:42:39 I don't have the knowledge to do much w/ sphinx links. 17:44:28 well, i'll hack away and see what happens 17:44:34 we need to end.this.meeting. 17:44:36 ;-) 17:44:39 yes, yes we do 17:45:02 #action acozine to create a PR with a page about "figuring out versions" 17:46:41 #action samccan to hack more mockups, maybe play w/ intersphinx 17:46:45 ok shall we end? 17:47:22 eventually I'd like to see a demo of the two-site idea - "here I am on the collections home page for 3.0, I can click here to do X, or here to do Y, now I'm on the 2.11 page for something, here's how it looks" 17:47:44 so whatever we can do to get ready for ^^^ (and maybe we're already ready) 17:48:06 yes, the meeting has gone on long enough 17:48:13 #endmeeting