15:01:08 <acozine> #startmeeting Docs Working Group aka DaWGs
15:01:08 <zodbot> Meeting started Tue Apr 27 15:01:08 2021 UTC.
15:01:08 <zodbot> This meeting is logged and archived in a public location.
15:01:08 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:08 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:08 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:01:13 <acozine> #topic opening chatter
15:01:14 <samccann> woot!
15:01:20 <acozine> who's around to talk docs?
15:01:22 <acozine> #chair samccann
15:01:22 <zodbot> Current chairs: acozine samccann
15:02:34 <acozine> andersson007_: dericcrago dmsimard aminvakil briantist cyberpear felixfontein jmn kindlehl madonius tremble you folks talking docs today?
15:03:20 <acozine> official agenda begins with https://github.com/ansible/community/issues/579#issuecomment-818898282 and continues with https://github.com/ansible/community/issues/579#issuecomment-827671912
15:03:30 <acozine> gundalow: I missed you in the roll-call above
15:03:47 <felixfontein> sorry, no time today...
15:03:56 <acozine> felixfontein: we'll miss you!
15:05:03 <acozine> if I didn't call your name, it means either 1) you haven't participated in the past, or 2) you have participated and I've forgotten, or 3) I just missed your name for no good reason at all
15:05:35 <acozine> everyone is welcome, first-timers especially!
15:05:59 <acozine> so if you're here and you want to participate, you can say hi or wave like this:
15:06:03 <acozine> o/
15:06:18 <samccann> possibly a quiet day today?
15:06:24 <acozine> seems like it, yeah
15:06:29 <acozine> Mr. Badger is on PTO
15:06:37 <acozine> so is Ms. Malivert
15:07:05 <samccann> Mr. Badger sounds like a kids book!  Mr. Badger's Adventures in Ansibleland!
15:07:07 <acozine> Mr. Fontein is out
15:07:13 <acozine> heh
15:07:26 <acozine> okay, I'll start posting news items
15:07:33 <samccann> cool
15:07:38 <samccann> with handing infos
15:07:50 <samccann> s/handing/handy/g
15:08:04 <acozine> #info ansible-core 2.11 was released yesterday (April 26)
15:08:35 <acozine> #info Ansible 2.9.21rc1 and 2.10.9rc1 are being cut today
15:09:17 <acozine> #info last week's DaWGs Mini Docs PR Day reviewed and merged or close 12 PRs, thanks to all who participated!
15:09:52 <samccann> We're a bit behind on publishing the core docs. But you can see the docs that will be 2.11 as the devel docs for now
15:10:19 <samccann> #info core docs are now at https://docs.ansible.com/ansible-core/devel/index.html
15:10:45 <acozine> We are also hard at work backporting all the docs PRs that have been merged into `devel` back into `stable-2.11`.
15:11:08 <samccann> <insert hardhat image here>
15:11:12 <acozine> heh
15:12:19 <acozine> we've updated the version-switcher on the /ansible/ docs so only three versions are available - `devel`, `latest` (which is 3), and `2.9`
15:12:53 <acozine> When Ansible 4 is released in a few weeks, we expect to remove 3 and add 4 as `latest`
15:13:03 <samccann> I'm thinking once 2.9 goes EOL someday, then we'll only have devel and latest, right?
15:13:37 <acozine> If folks decide to form a maintenance team for Ansible 3, we can keep both 3 and 4 in the rotation, but for now, we're not planning on it
15:13:56 <samccann> ^^ we should discuss as well.
15:14:19 <acozine> samccann: yes, when 2.9 goes EOL there will only be 2 options in the /ansible/ version-switcher, unless folks step forward to maintain other community versions
15:14:21 <samccann> in the sense that anyone who forms maintenance for it also supports docs backports etc as needed
15:14:53 <samccann> we can merge the backports etc, but we can't maintain the older docs
15:15:21 <acozine> true, docs maintenance will be part of the maintenance burden
15:15:41 <acozine> maybe i should change the topic . . .
15:16:05 <acozine> #topic versions and maintenance
15:16:15 <samccann> :-)
15:16:31 <acozine> #info version-switcher for /ansible/ docs now only shows `devel`, `latest` (which is 3) and `2.9`
15:16:48 <samccann> #info once Ansible 4  releases, it will become `latest` and Ansibl 3 docs will be EOL
15:17:23 <acozine> #info if a maintenance team steps forward for Ansible 3, we can add `3` to the mix, but maintainers will need to maintain docs (with backports) as well as code
15:18:12 <acozine> anything else on versions and related topics?
15:18:35 <acozine> tadeboro: you around to chat about docs?
15:18:37 <samccann> thinking
15:19:00 * tadeboro reporting for duty
15:19:03 <samccann> no I don't think there's anything else on version fun
15:19:16 <acozine> #chair tadeboro
15:19:16 <zodbot> Current chairs: acozine samccann tadeboro
15:19:26 <acozine> we're a small group today, several folks are out
15:19:35 <acozine> #topic Sphinx upgrade
15:19:58 <acozine> tadeboro: what's your rank?
15:20:24 <acozine> General? Lieutenant? Sergeant Major?
15:20:41 <tadeboro> Right now, I am a ship cook ;)
15:20:42 <samccann> They are the very model of a modern Major General...
15:20:45 <acozine> heh
15:21:01 <acozine> send some ship's biscuits and grog over, will you?
15:21:43 <acozine> #info WIP PR to upgrade the Sphinx version is open: https://github.com/ansible/ansible/pull/74372
15:22:22 <acozine> if we remove the limitation, folks may end up with different versions of Sphinx
15:22:40 <acozine> on the one hand, that means we don't have to worry about getting more and more behind
15:23:11 <acozine> on the other hand, we risk things breaking if there are changes in Sphinx that we were not expecting
15:23:25 <samccann> I think overall, in requirements files, we don't fix a version or range unless there's a need to, right?
15:23:41 <acozine> yeah, and I think that's the right approach here too
15:23:41 <samccann> as in we have that risk in all the packages we depend on in Ansible
15:23:45 <acozine> true
15:23:58 <samccann> and yeah it will bite is in the backside *cough* docutils *cough*
15:24:03 <acozine> yep
15:24:16 <tadeboro> Having no limit is good and bad at the same time: for seasoned contributors, this means they can help fix issues; for first time contributors, change in the Sphinx itself can make contributing a bit harder.
15:24:35 <acozine> I'm just feeling a bit tender in that part of my (technical) anatomy from recent bites
15:24:49 <acozine> tadeboro: yep
15:25:08 <acozine> do you have a preference for which risk we should run?
15:25:19 <samccann> yeah wondering how we track changes better from the upstream projects we depend on?
15:25:21 <tadeboro> But from my personal experience, staying behind the upstream is usually a bigger problem and would thus remove the upper bound as done in the PR.
15:25:41 <acozine> okay, sounds like the three of us are all in agreement
15:26:03 <samccann> We have the nightly builds that will show if there is a catastrophic failure
15:26:14 <tadeboro> How often do we regenerate the devel docs? If the frequency is more than once a month, that should reveal problems soon enough.
15:26:17 <acozine> #info if any folks have spare time this week, please test the latest Sphinx version with our docs
15:26:18 <samccann> but oddities in output it won't find *cough* docutils *cough*
15:26:32 <acozine> tadeboro: the devel docs run on an automated job
15:26:39 <acozine> it checks 4x per day for changes
15:26:48 <acozine> and publishes the docs if there are any changes
15:27:04 <acozine> that includes changes to the code, not just to the docs (it looks for merged PRs, basically)
15:27:18 <acozine> so if it fails, we know about it quickly
15:27:31 <samccann> yeah the problem is  what happened when docutils updated, broke the theme we depend on.. and things looked just a bit 'off'. People noticed etc and we patched around it.
15:27:32 <acozine> but, as samccann says, sometimes the job succeeds, but there are other problems in the docs
15:28:02 <samccann> So I guess the question is - is that an okay feedback loop? That devel docs are cutting edge and if things go bad, community will notice and let us know?
15:28:10 <acozine> I think so
15:28:29 <acozine> we can't expect perfection
15:28:31 <tadeboro> Breakages will always happen, so I think we just embrace them and let users report bugs when they find them.
15:28:53 <samccann> the only other option I can think of is if we start tracking upstream packages more closely so we can anticipate when a release is coming up there, then keep a closer eye on the impact in devel
15:29:11 <samccann> ok I can live with that :-)
15:29:59 <tadeboro> I have been generating docs using latest stable Sphinx for almost two years now for our collections and I think my build broke once in all that time.
15:30:14 <acozine> tadeboro: that's a good record
15:30:26 <acozine> looks like there's a sphinx-docs channel here in freenode IRC
15:30:38 <acozine> I might join that, see how much traffic it gets
15:30:42 <samccann> oh interesting
15:30:55 <acozine> https://www.sphinx-doc.org/en/master/
15:32:24 <acozine> #agreed we'd rather risk breakages with updates to Sphinx than face the problems of pinning to a known older version
15:33:26 <acozine> anything else on Sphinx?
15:33:38 <acozine> oh
15:33:46 <samccann> We have that PR somewhere on using the ansible theme the community created
15:33:58 <samccann> afaik that's waiting on fixes to that theme before we can go further.
15:34:16 <acozine> #info Sphinx has a channel called sphinx-doc here on freenode IRC, maybe one of the DaWGs can join that and keep tabs on upcoming changes
15:34:30 <acozine> #topic ansible Sphinx theme
15:35:00 <samccann> oh gosh now I gotta find that PR Lol!
15:35:07 <acozine> #info WIP PR: https://github.com/ansible/ansible/pull/74318
15:35:27 <samccann> oh you are on FIRE today! thanks!
15:36:33 <samccann> #info the ansible theme is pretty close to what we need, but have some requests in for changes to match our current look and feel and to support ansible-core docs with theme changes
15:36:38 <acozine> theme needs to support (or at least allow) multiple "look and feel" options, so we can differentiate the `ansible-core` docs from the `ansible` docs
15:36:53 <acozine> samccann: jinx
15:37:00 <samccann> heh
15:37:06 * samccann hands over a soda
15:37:15 * acozine chugs
15:38:51 <samccann> #action samccann to test sphinx 4.x beta as it has 'breaking changes' warning on it
15:39:25 <acozine> #info theme changes for `ansible-core` introduced in https://github.com/ansible/ansible/pull/74356; current ansible-core docs are published as https://docs.ansible.com/ansible-core/devel/
15:39:44 <acozine> wow, we're going to go from 2.x to 4.x in a few weeks?
15:39:49 <samccann> heh
15:40:01 <acozine> we're living in the future!
15:40:15 <samccann> more like let's see if things blow up horribly with sphinx 4. If so, we may need to pin it to < 4 until we can figure out what's going on.
15:40:18 <acozine> heh
15:40:42 <acozine> any other Sphinx wisdom? concerns? ideas?
15:40:49 <samccann> #info core theme changes support a different look so readers know they are not on the Ansible (package) docsite
15:41:36 <acozine> #topic searching and sitemaps for the `ansible-core` docs
15:41:59 <acozine> this topic may need a few weeks of discussion
15:42:29 <acozine> a lot of documentation is duplicated on `docs.a.c/ansible/` and `docs.a.c/ansible-core`
15:42:40 <acozine> which is confusing for search engines, and makes for bad SEO
15:43:02 <acozine> so far the site search has only been turned on for `/ansible/`
15:43:12 <acozine> and we only have a sitemap for `/ansible/`
15:43:56 <acozine> there are a few pages that ONLY appear on `/ansible-core/` docs, mainly the core roadmaps
15:44:27 <acozine> the porting guides are different on `/ansible-core/` but the core items are included in the larger `/ansible/` porting guides
15:44:42 <acozine> so the question is . . .
15:45:15 <acozine> how much do people want to use the site search on the `/ansible-core/` documentation?
15:45:31 <acozine> right now, if they do, the results will take them to `/ansible/latest`
15:45:34 <samccann> There are a couple of options we can go with
15:45:47 <samccann> we can turn off the swiftype search for core docs and go back to opensearch.
15:46:15 <samccann> OR we could create a new search engine target specific for ansible-core so the search would only pick up core docs
15:47:21 <tadeboro> I must admit I never used the search functionality on docs.a.c, I just limit the search directly in the search engine.
15:47:46 <tadeboro> And I have a feeling that I am not alone here.
15:47:51 <samccann> heh
15:47:57 <acozine> yeah, most of our traffic comes from google
15:48:03 <samccann> very true.
15:48:12 <tadeboro> So making sure SEO is right is probably more important than getting search functionality right.
15:48:34 <acozine> so messing up the google results for the sake of better local sitesearch seems like a step backwards
15:48:53 <samccann> not sure how that happens? ^^
15:48:59 <samccann> what are you envisioning there acozine?
15:49:34 <acozine> if we publish a sitemap for ansible-core, google will index it and might start returning those pages instead of `/ansible/latest`
15:49:40 <samccann> cyb-clock sez we are 50 min into the meeting
15:49:43 <acozine> heh
15:49:58 <samccann> yeah agreed. I think we do NOT do a sitemap for ansible-core
15:50:19 <samccann> but we could still replace the site search with 'something better' that would presumably have no impact on the googles of the world
15:51:02 <tadeboro> Is there a non-technical reason behind the dupplication of content between ansible and ansible-core sites?
15:51:26 <samccann> There were two reasons I remember:
15:51:33 <samccann> 1 - core releases separately from Ansible
15:51:51 <samccann> 2 - Folks felt it was important to have a COMPLETE website
15:51:56 <acozine> also
15:52:05 <samccann> as in, we couldn't have ansible-core on one site, and al lthe collections on another site
15:52:11 <acozine> 3 - core maintenance is different from Ansible maintenance
15:52:26 <acozine> ansible-base 2.10 is still maintained, even though Ansible 2.10 is not
15:53:51 <tadeboro> Hmm, when I search for common stuff (like playbook keywords), I would expect search engine to serve me results from ansible-core.
15:54:27 <acozine> would you? instead of from the latest version of Ansible (which is based on an older ansible-core version)?
15:54:45 <tadeboro> But maybe I am not the right person to design this for since I know too much about the ansible-core vs. ansible and I can navigate my way around.
15:55:05 <acozine> that's another difference, there is no `latest` for ansible-core
15:55:19 <acozine> heh
15:55:27 <acozine> we have that same problem
15:55:55 <acozine> I can't really imagine what the site looks like to someone who doesn't already know her way around
15:56:00 <bcoca> first, how are downstream packaging it? are they still using the 'ansible' package, are they offering a 'core' package or both?
15:56:18 <samccann> neither afaik
15:56:21 <bcoca> ^ big chunk of users will consume from OS package
15:56:32 <bcoca> samccann: so they stopped offering ansible as OS package?
15:56:35 <samccann> oh downstream as in other OS's
15:56:47 <bcoca> yes
15:56:54 <samccann> RHEL is TBD. I don't know if it will be in RPMs etc
15:57:09 <samccann> as for something like Debian, dunno. maybe relrod knows what they are doing?
15:57:10 <bcoca> RHEL is special case
15:57:30 <bcoca> debian, ubuntu, freebsd, centosalternativescauseusersaremiffedwithRH
15:57:45 <bcoca> amazon linux ...
15:58:06 <tadeboro> For Red Hat, all I found is "here is how you should use execution environments". For other distros, I am not really sure since my method of installing ansibleis venv.
15:58:33 <samccann> this is ubuntu - https://launchpad.net/~ansible/+archive/ubuntu/ansible
15:58:38 <samccann> and looks like it's base only
15:59:08 <tadeboro> Gentoo has ansible and ansible-base.
15:59:12 <bcoca> well, RHEL assumes 'paying customer' and AAP .. so again, special case
15:59:12 <acozine> I see both (on the upper right)
15:59:30 <tadeboro> https://packages.gentoo.org/packages/search?q=ansible
15:59:33 <acozine> (both ansible and ansible-base on the ubuntu page)
15:59:40 <bcoca> ^ that ppa which 'WE' control, but not what OS ships with
16:00:23 <samccann> acozine look at the actual package numbers for ubutu - 'ansible' is 2.9 only
16:00:31 <bcoca> right now most distros are still shipping 2.9
16:00:48 <acozine> heh
16:00:54 <bcoca> why i ask if ther eis any info on what they plan for > 2.9
16:01:08 <samccann> cyb-clock sez we are 1 hr into the meeting
16:01:10 <bcoca> cause that will 'taint' how we want to present info for users in the end
16:01:16 <acozine> okay
16:01:20 <relrod> the PPA is being maintained by the Community team going forward. So ansible-core hasn't landed there yet. Though the Core team still currently drops 2.9 and 2.10 updates there.
16:01:22 <acozine> we are not going to solve this today, that's for sure
16:01:59 <acozine> let's keep it on the agenda for next week
16:01:59 <samccann> sorry what's the PPA? lost track on that
16:02:00 <bcoca> relrod: why i quoted 'we'
16:02:17 <relrod> samccann: Ubuntu/Debian packages
16:02:20 <acozine> PPA is an auxiliary package, an add-on
16:02:21 <bcoca> samccann: page linked above, its 'repo available to distro but not part of distro (ubuntu)'
16:02:23 <samccann> ok thanks
16:02:50 <bcoca> though they work with every debian derivative, its mostly an ubuntu sponsered '3rd party stuff here' repo facility
16:02:58 <samccann> #info need to keep this discussion open  - what are the distros doing with ansible vs ansible core etc. Gentoo seems to have both for example
16:03:15 <acozine> let's do a quick open floor
16:03:28 <acozine> #topic open floor
16:03:40 <acozine> all questions, comments, suggestions, ideas welcome
16:04:11 <acozine> if you have an open PR and need reviews, you can post it
16:04:31 <acozine> if you have a question about using the docs, you can ask it
16:05:10 <acozine> if you have a critique of a page, or a suggestion for improving the docs, you can discuss it
16:05:25 <acozine> this meeting happens every week at this same time
16:05:49 <acozine> anyone can add items to the agenda at the bottom of https://github.com/ansible/community/issues/579
16:06:05 <acozine> and/or you can bring any topic up during the open floor
16:06:33 * acozine stops typing for a minute . . .
16:07:32 <acozine> hearing no open floor items . . . .
16:07:49 <acozine> thanks tadeboro samccann bcoca relrod
16:08:08 <acozine> chat welcome in the channel at all times!
16:08:10 <acozine> #endmeeting