14:30:27 <acozine> #startmeeting Docs Working Group aka DaWGs
14:30:27 <zodbot> Meeting started Tue Dec  1 14:30:27 2020 UTC.
14:30:27 <zodbot> This meeting is logged and archived in a public location.
14:30:27 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:30:27 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:30:27 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:30:35 <acozine> #topic opening chatter
14:30:37 <acozine> who's around?
14:31:11 <lmodemal> Hello o/
14:31:12 * dericcrago waves
14:31:13 <samccann> \o
14:31:49 <acozine> today is a Big PR Review Day, what would folks think of cutting the DaWGs meeting short and joining that meeting at the top of the hour?
14:32:09 <acozine> #chair lmodemal dericcrago samccann
14:32:09 <zodbot> Current chairs: acozine dericcrago lmodemal samccann
14:32:23 <samccann> +1
14:32:48 <dericcrago> +1
14:33:15 <acozine> anybody else around?
14:33:21 <lmodemal> +1
14:34:13 <acozine> andersson007_: baptistemm briantist cyberpear felixfontein madonius persysted tadeboro tremble tributarian you folks chatting docs today?
14:34:50 <tributarian> im game
14:34:56 <tadeboro> I am here, not yet looked at the agenda, all for "lets make this meeting short" ;)
14:35:10 <dmsimard> afk for a while longer sorry
14:35:30 <acozine> #chair tributarian tadeboro
14:35:30 <zodbot> Current chairs: acozine dericcrago lmodemal samccann tadeboro tributarian
14:35:35 <acozine> dmsimard: np
14:35:40 * gundalow waves
14:36:04 <acozine> #chair gundalow
14:36:04 <zodbot> Current chairs: acozine dericcrago gundalow lmodemal samccann tadeboro tributarian
14:36:22 <acozine> agenda is mostly follow-up items, looks like
14:36:23 <acozine> https://github.com/ansible/community/issues/521#issuecomment-733085061
14:37:08 <acozine> it was a holiday in the US last week
14:37:18 <acozine> and I for one am still not "back in the swim"
14:37:49 <samccann> heh
14:38:39 <acozine> #topic redirects post 2.10
14:39:10 <acozine> this topic has been on the agenda for a while, and we've skipped it several weeks in a row
14:40:07 <samccann> can you summarize? I've forgotten what it's about
14:40:32 <acozine> the issue is this: right now we are redirecting to and from the old module docs URLs (.../modules/name_of_module.html) to (and from) the new module docs URLS (.../collection/type/name_of_module.html)
14:40:55 <acozine> we do this for 2.9 and `latest` (currently 2.10)
14:41:19 <acozine> so if someone is looking at the docs for a single module in the 2.9 docs
14:41:40 <acozine> and they use the version-switcher to move to `latest`, they get redirected to the equivalent page
14:42:02 <acozine> this also works for folks who have bookmarks for a module in `latest` that were made when 2.9 was `latest`
14:42:37 <acozine> and it works moving backward, so if you want the non-collections equivalent of a 2.10 module doc, you can use the version-switcher
14:42:39 <samccann> k
14:43:06 <acozine> this means we maintain one redirect per module per version
14:43:15 <acozine> right now it's only 2 versions
14:43:56 <acozine> as we move forward, how important is it to maintain those redirects?
14:44:04 <tributarian> I use them all the time.
14:44:17 <acozine> tributarian: good to know
14:44:25 <tributarian> But I don't have to maintain them, so I'm not sure if it's worth it
14:44:26 <acozine> how do you use them?
14:44:38 <acozine> with the version-switcher?
14:44:42 <acozine> or old links?
14:44:49 <tributarian> My primary way of searching for ansible documentation is google. Which frequently directs me to the wrong version.
14:44:49 <acozine> or some other scenario I haven't thought of?
14:44:51 <samccann> can we just say we'll maintain it for 2.9 <--> latest?
14:45:00 <tributarian> I use the version switcher to get me to the version I am running.
14:45:02 <samccann> for whatever is latest?
14:45:28 <tributarian> For instance i am currently working on  a Tower instance which is 2.9
14:45:33 <acozine> tributarian: so google sends you to `latest` and you version-switch to go back to 2.9?
14:45:38 <tributarian> not always
14:45:47 <tributarian> sometimes i get 2.6 or other older versions
14:45:59 <acozine> oof, that's not good
14:46:18 <tributarian> i use google instead of the docs search because it incorporates blogs which can sometimes clarify odd use cases
14:46:39 <acozine> yeah, that's fine
14:46:40 <tributarian> yeah the 2.6 was an outlier, I can't remember what I was searching for.
14:46:54 <acozine> the "not good" part was for hitting an end-of-life version
14:47:01 <tributarian> For sure
14:47:08 <acozine> if you hit that again, would you mind reporting it here?
14:47:14 <tributarian> Sure
14:47:21 <acozine> thanks
14:47:36 <tributarian> https://startpage.com/do/metasearch.pl?query=ansible%20include%20tags
14:47:47 <tributarian> second result shows https://docs.ansible.com/ansible/2.6/user_guide/playbooks_tags.html
14:48:08 <tributarian> got lucky and remembered the query
14:48:31 <acozine> awesome, thank you
14:48:41 <acozine> first result is latest, so I think that's okay
14:49:02 <acozine> we can't erase the old docs from google searches entirely, unless we remove them from the site
14:49:11 <dericcrago> I just searched `ansible yum module`, top 3 results were: latest, 2.3, 2.5 (in that order) - https://www.google.com/search?q=ansible+yum+module
14:49:11 <samccann> the redirects we are discussing are for modules.  The user guide pages etc should still work
14:49:26 <acozine> dericcrago: sigh
14:49:52 <tributarian> samccann: Ah, understood
14:50:00 <acozine> samccann: true, we don't need redirects for pages like playbooks_tags.html
14:50:02 <samccann> anyone familiar w/ robots for blocking search results?  we 'could' try that for the older EOL docs
14:50:28 <dericcrago> based on the breadcrumbs google provides, it's not immediately obvious (to me at least) which one is latest until I click on it
14:51:43 <acozine> we should probably update the robots.txt files
14:52:00 <dericcrago> what I saw when I googled `ansible yum module` https://pasteboard.co/JCV9BqR.png
14:52:25 <samccann> acozine - not sure - do we even have any robots.txt files for ansible/ansible?
14:52:35 <acozine> samccann: I think we do
14:52:43 <acozine> but I haven't looked at them in a long time
14:52:45 <acozine> or it
14:53:03 <acozine> dericcrago: your search results don't show the URLs at all, that's weird
14:53:15 <samccann> #info search results do still return older docs for modules (2.6, 2.3, etc).  Can we find a way (robots.txt??) to have search engines ignore EOL pages ?
14:53:22 <acozine> but that top result is for 2.10
14:53:35 <acozine> it shows `builtin` in the breadcrumbs
14:53:44 <acozine> so it's collections-based
14:53:55 <acozine> but I pulled us off-topic
14:54:07 <acozine> by going down the google results rabbit-hole
14:54:12 <acozine> (so, so tempting!)
14:54:44 <tributarian> I know it isn't a redirect, but the way the userguide handles page changes is also nice. e.g. https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_includes.html
14:54:45 <acozine> we're looking for a sense of how valuable the redirects for module docs are
14:55:24 <samccann> so is the question - when Ansible 2.11 releases, do we - replace the redirects so that it becomes 2.9 <---> latest/2.11
14:55:26 <samccann> OR
14:55:48 <samccann> do we ADD 2.9<--> 2.11 (aka keep adding more and more redirects for each Ansible release?
14:55:54 <samccann> is that the basic question?
14:55:55 <felixfontein> hi!
14:55:59 <acozine> felixfontein: hi!
14:56:00 <felixfontein> sorry, only partially around
14:56:19 <acozine> np, we're almost done for today - PR reviews starting in five minutes
14:56:27 <acozine> samccann: the question is this:
14:57:02 <acozine> when do we stop putting redirects in for the module docs?
14:57:08 <acozine> and possible answers include: never
14:57:42 <acozine> or, we only do it for `latest` (in which case switches to 2.10 from 2.9-style URLs would 404)
14:58:02 <acozine> or, we maintain it for all versions until all maintained versions are collections-based
14:58:09 <acozine> or, we maintain it for all versions for eternity
14:58:22 <acozine> probably other options I haven't thought of
14:58:39 <tributarian> I would vote for "or, we maintain it for all versions until all maintained versions are collections-based" since that is only 2 more releases?
14:58:41 <acozine> but the main question is, how important/useful are those redirects?
14:58:59 <felixfontein> tributarian: 2.9 is LTS, so it will stay for quite some time
14:59:00 <acozine> tributarian: I think 2.9 will be with us for at least 2 years
14:59:07 <tributarian> Bummer
14:59:11 <samccann> yeah was just thinking that
14:59:47 <acozine> we could set up a "big hammer" redirect that sends old-style URLs to the collections index page
14:59:51 <tributarian> I would almost rather not have redirects than have them sometimes work (or, we only do it for `latest` (in which case switches to 2.10 from 2.9-style URLs would 404))
15:00:00 <acozine> which would be one step less obnoxious than a 404
15:00:12 <samccann> thinking out loud.  if we keep the redirects pointing to 'latest'.. then 2.9 to latest always works (and visa-versa).  so we get people from the old world to the new world
15:00:13 <tributarian> That seems reasonable
15:00:25 <tributarian> The hammer approach
15:00:32 <samccann> do we need to get people from the 2.10 world back to 2.9? (once 2.11 is available)?
15:00:58 <tributarian> That is a good question, maybe not.
15:01:04 <acozine> if we want perfection, we'll also need redirects between 2.10 and 2.11 where modules have moved from one collection to another
15:01:05 <tadeboro> What does 2.11 even mean? ansible-core-2.11 or ansible-3.0.0?
15:01:18 <acozine> grrrrrrr
15:01:20 <acozine> NOT 2.11
15:01:22 <acozine> 3.0
15:01:24 <acozine> thanks tadeboro
15:01:25 <samccann> we don't currently have 2.8 redirects
15:01:30 <samccann> grrrr
15:01:34 <samccann> sorry yeah... 3.0.0
15:01:44 <acozine> old habits die hard
15:01:47 <samccann> indeed
15:02:15 <acozine> I really wish we had a way to tell how many times the redirects get used today
15:02:39 <acozine> but the only way I can think of is to look at the webserver logs, and that's not a realistic option
15:02:52 <dericcrago> are we talking about web server redirects? such that when I accidently ended up at `https://docs.ansible.com/ansible/2.5/modules/yum_module.html` from my google search and replaced `2.5` with `latest` in the url, I get redirected to `https://docs.ansible.com/ansible/latest/collections/ansible/builtin/yum_module.html`? (I've used that method a fair amount)
15:03:04 <felixfontein> btw, I plan to work on adding meta/runtime.yml / symlink redirect knowledge to antsibull-docs soon, so that if something is moved between 2.10 and 3.0.0, one doesn't get a 404 when switching from 2.10 to 3.0.0 but a stub page which says where it went. (won't help when switching from 3.0.0 to 2.10 though)
15:03:04 <acozine> dericcrago: yes
15:03:58 <acozine> felixfontein: that is awesome
15:04:12 <dericcrago> I would certainly miss that if the google results weren't cleaned up somehow
15:04:58 <acozine> sounds like the redirects are useful
15:05:22 <acozine> oops, and it's five minutes past the hous
15:05:26 <acozine> s/hous/hour
15:05:28 <samccann> but are they useful beyond latest?
15:05:29 <baptistemm> ah I missed the doc meeting, new times are too disruptive for me
15:05:46 <acozine> baptistemm: np, it's a short one today
15:05:55 <samccann> #info people do still replace /2.5/ for /latest/ in the url when they get the wrong version result from google.
15:06:01 <dericcrago> I was getting confused with the version switcher dropdown, but it looks like you only get that if you're on a recent enough version to start with
15:06:02 <tadeboro> But mostly because search engines return results from ancient history.
15:06:24 <acozine> next week I'll try to put a reminder about the earlier time in the channel on Monday
15:06:39 <tadeboro> I would vote for "let us try do a bit of SEO" and  "keep redirects from 2.9 to latest".
15:06:43 <samccann> #action samccann acozine  -investigate options to remove EOL pages from all search results (robots.txt??)
15:07:06 <tadeboro> I feel it is a decent compromise between user friendliness and maintenance burden.
15:07:13 <samccann> Do we need to consider pushing this meeting back an hr to 10:30am ET like the community team did?
15:07:16 <briantist> yes I still replace `<version>` with `latest` when I get the wrong result from google
15:07:35 <briantist> it happens less now that names are FQ though, because I can see visually in the results which ones are "modern"
15:07:36 <gundalow> samccann: Yes I manually hack the url `/2.5/` -> `/latest/` if I notice it
15:08:42 <acozine> thanks for a great discussion, folks!
15:08:48 <briantist> as a small aside, google is still the main (best) way to find anything. I foolishly tried again to use the search in the docs a few days ago and it was frustrating, went right back to web search
15:09:09 <acozine> we'll do a quick open floor, then migrate over to the PR Review Day
15:09:23 <acozine> briantist: yes, our site search could definitely use tuning
15:09:39 <acozine> #topic open floor
15:09:53 <felixfontein> briantist: what did you search for?
15:10:02 <acozine> gundalow: which channel is the PR day on? ansible-community? or ansible-meeting? or?
15:10:11 <felixfontein> #ansible-community
15:10:14 <felixfontein> (it already started)
15:10:44 <acozine> felixfontein: thanks (yeah, we are running a bit behind as usual ;-) )
15:10:46 <briantist> felixfontein a few things,  I remember `win_shell` being one of them
15:11:34 <acozine> all questions, comments, suggestions welcome
15:11:57 <acozine> as a reminder, anyone can add an item to the DaWGs agenda
15:12:14 <acozine> just add a comment to https://github.com/ansible/community/issues/521
15:12:33 <acozine> also, we will have a supplemental meeting this Thursday
15:12:34 <samccann> begging for feedback on - https://hackmd.io/@IfPUJ5PTRbmMT7hHdBF-OA/SJmrZMQcw
15:12:48 <samccann> #info please review docsite split proposal before Thursday - https://hackmd.io/@IfPUJ5PTRbmMT7hHdBF-OA/SJmrZMQcw
15:13:07 <samccann> we need to start implementing it (or SOMETHING) if we have a hope of making an Ansible 3.0.0 deadline
15:13:08 <acozine> supplemental meeting starts at 10:30 Eastern time on Thursday
15:13:33 <samccann> #info supplemental meeting to discuss docsite split happens at 10:30am ET on Thursday
15:14:20 <gundalow> acozine: This and PR day can run in parallel, please continue the docs meeting :)
15:14:44 <acozine> topic for supplemental meeting is "how do we document Ansible 2.9, Ansible 2.10, Ansible 3.0 and ansible-core 2.12 and make it clear which features are available in which version of which thing"
15:15:10 <acozine> gundalow: no worries, the supplemental meeting is one we've been doing for a while, not related to the PR day
15:16:23 <acozine> anything else for open floor?
15:17:59 <acozine> thanks baptistemm briantist dericcrago felixfontein gundalow lmodemal samccann tadeboro tremble tributarian
15:18:10 <acozine> #endmeeting