15:00:57 <acozine> #startmeeting Docs Working Group aka DaWGs
15:00:57 <zodbot> Meeting started Tue Apr 13 15:00:57 2021 UTC.
15:00:57 <zodbot> This meeting is logged and archived in a public location.
15:00:57 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:57 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:57 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:01:01 <acozine> #topic opening chatter
15:01:04 <acozine> who's around?
15:01:05 <felixfontein> o/
15:01:09 <felixfontein> (half-way :) )
15:01:12 <acozine> heh
15:01:18 <acozine> you want to be furniture, felix?
15:01:31 <kindlehl> o/
15:01:32 <lmodemal> O/
15:01:43 <acozine> #chair kindlehl lmodemal
15:01:43 <zodbot> Current chairs: acozine kindlehl lmodemal
15:01:49 <samccann> o/
15:01:55 <abadger1999> Bom dia
15:02:05 * dericcrago waves
15:02:29 <acozine> abadger1999: andersson007_ dericcrago dmsimard gundalow aminvakil baptistemm briantist cyberpear persysted Tas-sos tremble tributarian you folks talkign docs today?
15:02:34 * samccann winds up cyb-clock
15:02:43 <acozine> heh, in the time it takes me to scan the members list badly . . .
15:02:50 <abadger1999> :-)
15:02:59 <acozine> #chair samccann abadger1999
15:02:59 <zodbot> Current chairs: abadger1999 acozine kindlehl lmodemal samccann
15:03:04 <acozine> #chair dericcrago
15:03:04 <zodbot> Current chairs: abadger1999 acozine dericcrago kindlehl lmodemal samccann
15:03:30 <acozine> felixfontein: wave again if you want to be a chair . . .
15:03:34 <abadger1999> When I ran meetings in the past, I had a list of people to ping in a "running the meeting doc" that I could cut and paste into IRC at the start of the meeting.
15:03:46 <acozine> abadger1999: ah, that's a good idea
15:04:50 <acozine> official agenda for today: https://github.com/ansible/community/issues/579#issuecomment-814258612
15:05:28 <felixfontein> o/ :)
15:05:36 <acozine> #chair felixfontein
15:05:36 <zodbot> Current chairs: abadger1999 acozine dericcrago felixfontein kindlehl lmodemal samccann
15:05:43 <felixfontein> (I would have waved earlier but then I just had a phone call...)
15:05:55 <acozine> no worries
15:05:59 <acozine> welcome, folks!
15:06:00 <felixfontein> abadger1999: I have that for the community meeting ;)
15:06:13 <felixfontein> (I probably have to update it from time to time)
15:06:13 <dmsimard> \oà
15:06:19 <dmsimard> \o*
15:06:20 <acozine> #chair dmsimard
15:06:20 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein kindlehl lmodemal samccann
15:06:27 <samccann> hah is that a wave with sass?
15:06:35 <dmsimard> it's a wave with a typo :)
15:06:39 <acozine> heh
15:06:43 <dmsimard> à is next to my enter key in my keyboard layout
15:06:49 <acozine> I thought it was a language-specific wave
15:07:28 * samccann cyb-clock sez 7 min into the meeting and current topic
15:07:54 <acozine> thank you, samccann aka cyb-clock!
15:08:16 <acozine> #topic Reminder of next week's PR Review Day
15:08:54 <acozine> #info next Tuesday April 20 we will have a Docs PR Review Day
15:09:15 <samccann> woot woot!!
15:09:34 <dmsimard> oh neat, is that in the bullhorn ?
15:09:37 <acozine> #info easy way to find docs PRs: https://github.com/ansible/ansible/pulls?q=is%3Apr+is%3Aopen+label%3Adocs
15:09:47 <acozine> dmsimard: erm, I don't think so
15:10:01 <acozine> at least, I didn't put it in
15:10:05 <acozine> when does the next issue go out?
15:10:27 <samccann> this week
15:10:29 <samccann> I can add it
15:10:33 <acozine> awesome
15:10:37 <dmsimard> hmmmmm last one was 04/01/2021 so I think it'd be this week yeah
15:10:41 <samccann> #action samccann add docs PR day to bullhorn
15:10:49 <acozine> you beat me to it :-)
15:11:31 <acozine> the count is getting really high
15:11:43 <acozine> we're at 106 today
15:12:07 <acozine> at one time we had it down under 75 (three pages on the GitHub UI)
15:12:12 <acozine> I'd like to see us reach that again
15:12:42 <acozine> or even try to get the count lower if we can
15:12:55 <samccann> cool
15:13:09 <acozine> and we could look at docs PRs on other repos as well
15:13:18 <acozine> so bring your PRs yearning to be merged!
15:13:53 <acozine> (sorry, bad reference to the poem on the Statue of Liberty in New York . . .)
15:14:41 <abadger1999> :-)  Emma Lazarus
15:14:45 <samccann> Docs PRs that is ;-)
15:15:09 <acozine> heh
15:15:20 <acozine> should we just do the standard hour?
15:15:28 <acozine> extend it earlier?
15:15:33 <acozine> extend it later?
15:15:50 <dmsimard> for the PR day you mean ?
15:15:55 <acozine> dmsimard: yes
15:16:12 <acozine> I feel like we talked about this, but it's not in the minutes from last week
15:16:24 * acozine searches the log
15:16:31 <dmsimard> 1 hour definitely flies by and doesn't feel sufficient for a PR "day" :)
15:16:52 <abadger1999> I remember the term "half-day"
15:17:13 <samccann> yeah it's starts at 10AM ET and lasts 1/2 a day. it was in the meeting notes
15:17:18 <samccann> and just put that in the bullhorn
15:17:32 <acozine> phew
15:17:45 <acozine> thanks abadger1999 samccann dmsimard
15:17:46 <dmsimard> sounds sensible to me, though it would overlap with typical ET lunch time
15:18:41 <acozine> #agreed Mini Docs PR Day to start at 10AM Eastern time and last 4 hours on April 20
15:18:48 <dmsimard> I don't mind FWIW, just pointing it out
15:19:22 <acozine> I agree that even a "mini PR day" should be more than an hour, just couldn't remember what we discussed
15:19:26 <samccann> cyb-clock sez we are 19 minutes into the meeting, 11 minutes on the current topic
15:19:31 <acozine> it might be covid-brain
15:19:39 <lmodemal> I think we discussed 4hrs
15:19:45 <kindlehl> I recall 4 hours
15:19:46 <samccann> yep
15:20:00 <kindlehl> one hour before DaWGs and extending for 4 hours
15:20:02 <lmodemal> no one has to be on the entire 4hrs, but it's enough to cover timezones
15:20:35 <acozine> excellent
15:20:39 <samccann> thanks kindlehl and lmodemal !
15:20:44 <lmodemal> You're welcome
15:20:48 <kindlehl> ^
15:20:57 <acozine> #topic package `devel` docs
15:21:39 <acozine> any updates on getting the most recent releases of collections to publish to docs.ansible.com/ansible/devel/ ?
15:22:09 <abadger1999> No... I worked on the breadcrumb toggle switch this week.
15:22:14 <abadger1999> Almost done with a PR for that.
15:22:29 <acozine> that sounds great abadger1999
15:23:02 <abadger1999> I refamiliarized myself with the code that generates stable and how it could be split up to reuse in the devel docs though.
15:23:03 <acozine> oh, something that wasn't on the agenda
15:23:09 <abadger1999> So I have a plan for how to refactor that portion.
15:23:20 <acozine> better and better
15:23:42 <abadger1999> I did not evaluate further than that though.
15:24:18 <acozine> slow and steady, we'll get there
15:24:46 <abadger1999> I will commit to having some code to show for next week although probably not ready to generate any PoC websites to look at yet.
15:25:15 <acozine> that would be great
15:25:27 <samccann> #action abadger1999 to start work on devel for Ansible package docs (some coding, not PoC yet)
15:25:58 <samccann> should we switch topics to the breadcrumbs then?
15:26:29 <acozine> #topic breadcrumbs
15:26:39 <abadger1999> Cool :-)
15:26:46 <acozine> having the topics in the minutes is good
15:27:11 <abadger1999> So, update on the toggle switch code: I have everything plumbed through except for the cli arg itself.
15:27:16 <abadger1999> I should have that later today.
15:28:01 <acozine> heh, can we call the arg `--Gretel`?
15:28:03 <abadger1999> I've turned up a bunch of refactoring and some code cleanup I want to do in those same areas but I'll split between this PR, a separate PR, and the devel docs PR.
15:28:06 <abadger1999> :-)
15:28:12 <samccann> AAHAHA
15:28:19 <abadger1999> I can add an easter egg ;-)
15:28:32 * dmsimard lacks context to find --Gretel funny
15:28:52 <acozine> dmsimard: Hansel and Gretel used breadcrumbs . . .
15:28:54 <abadger1999> Search for the  children's fairy tale of Hansel and Gretel and the gingerbread house.
15:29:07 <felixfontein> lol
15:29:13 <dmsimard> oh, I know the name but didn't make the connection to breadcrumbs haha
15:29:20 <dmsimard> thanks :P
15:29:29 <acozine> that's why "links that help you find your way back" are called "breadcrumbs"
15:29:49 <abadger1999> acozine: How is the conversation to add docs builders with more memory to jenkins?
15:29:56 <acozine> though really, it's a bad metaphor, because Hansel and Gretel didn't find their way back in the story . . .
15:30:02 <acozine> abadger1999: stuck
15:30:08 <acozine> it went like this:
15:30:11 <abadger1999> Like a lot website UI design ;-)
15:30:22 <acozine> "could we get more memory on jenkins?"
15:30:32 <acozine> "yes, as soon as our team is less swamped"
15:30:49 <acozine> I will ping them gently again
15:30:55 <abadger1999> <nod> :-/
15:31:18 <samccann> is jenkins still failing sporadically?
15:31:33 <acozine> it looked all-green yesterday
15:31:41 <acozine> and I published a couple of things, all succeeded
15:31:55 <acozine> but we're not publishing the breadcrumbs yet
15:31:58 <samccann> sigh, one of the batch I started before this meeting failed
15:32:04 <samccann> so yeah, still failing sporadically
15:32:45 <acozine> #action acozine to request more resources for Jenkins
15:33:14 <acozine> anything else on breadcrumbs?
15:33:21 <samccann> so is the breadcrumb PR dependent on more jenkins muscle?
15:33:35 <acozine> yeah, it publishes fine locally with enough resources
15:33:51 <acozine> so with more resources we can publish it to production
15:34:23 <acozine> the current round of work is allowing us to turn it on/off with a switch, which will save resources when the breadcrumbs are not needed
15:34:25 <samccann> ok I'm a little lost.. what is the breadcrumb pr gonna do then?
15:34:49 <acozine> let us implement it, but with a switch to turn it off when needed
15:35:03 <acozine> right now it's been rolled back so we can keep publishing
15:35:09 <samccann> but if we turn it on, we can't publish right?
15:35:49 <acozine> we'd be able to run the jenkins build with `--noBreadCrumbs` or whatever the switch is, until we get the necessary resrouces
15:35:54 <abadger1999> A command line argument to turn breadcrumbs on.  We'll have to leave it off in production until the jenkins builders are upgraded with more menory.  Once they add more memory, you'll be able to test that it has fixed the problem.
15:36:33 <samccann> #info the PR is A command line argument to turn breadcrumbs on.  We'll have to leave it off in production until the jenkins builders are upgraded with more memory.  Once they add more memory, you'll be able to test that it has fixed the problem.
15:36:37 <samccann> cool thanks
15:36:53 <acozine> good clarification
15:37:14 <acozine> #topic other updates
15:37:15 <samccann> cyb-clock sez 37 minutes into the meeting, 10 minutes into current topic
15:38:03 <acozine> I have no update on the prototype Scenario Guide move-to-collections PR
15:38:12 <acozine> that is, I have not made progress on it
15:38:18 <acozine> I will try again this week
15:38:42 <acozine> though I've got mandatory training again today . . .
15:39:43 <acozine> does anyone have other updates on the "usual suspects" topics?
15:39:53 <samccann> none from me
15:40:12 * acozine waits a minute or two
15:41:02 <acozine> hearing none . . .
15:41:06 <acozine> #topic open floor
15:41:16 <acozine> I have a topic for the open floor today
15:42:13 <acozine> we updated the "look and feel" of the ansible-core documentation by changing the teal ("lake") color to a dark grey
15:42:16 <acozine> https://docs.ansible.com/ansible-core/devel/
15:42:45 <acozine> we're hoping that this will help users recognize when they are reading the package docs and when they are reading the ansible-core docs
15:43:03 <samccann> shoot. can you see the section titles in the left hand nav?
15:43:06 <dmsimard> I noticed the styling issue was fixed, good job figuring that out
15:43:30 <acozine> samccann: ah, only sort of
15:43:33 <samccann> dmsimard - still a temp patch
15:44:17 <acozine> okay, if anyone sees *other* problems with the ansible-core CSS, or ways to make the difference more obvious, please bring them to this chat channel
15:44:17 <samccann> yeah didn't look so dark on the left-hand nav in test. We'll have to poke around on that one. I bet it was one teal to black change too many but we didn't notice because the PR still had that style issue
15:44:26 <acozine> now, later, any time
15:44:53 <samccann> cyb-clock sez we are 45 min into the meeting
15:45:08 <acozine> I'm not a CSS expert
15:45:27 <acozine> so I'd appreciate any help or pointers folks may have
15:45:28 <samccann> #info core docs have a new look to make it distinct from Ansible pkg docs - https://docs.ansible.com/ansible-core/devel/
15:45:52 <samccann> acozine we can work on it after mandatory training. I think it's just one of those teal to black changes has to go back to teal
15:46:04 <acozine> #info change to core docs came from https://github.com/ansible/ansible/pull/74200/commits
15:46:46 <samccann> i have an open floor item but does anyone else have anything before I bring it up?
15:46:52 <kindlehl> Its kind of hard to read the sidebar headings
15:47:03 <acozine> kindlehl: thanks, yeah, the contrast is not great
15:47:05 <kindlehl> on the ansible-core/devel docs
15:47:45 <acozine> a few experiments are going to be necessary!
15:48:58 <samccann> bcoca are you around?
15:49:15 <samccann> thought we'd discuss https://github.com/ansible/ansible/pull/74245
15:50:18 <samccann> hmm maybe not
15:50:45 <samccann> the gist of the question is - what should that docs URL point to - ansible docs, core docs? some intelligent combination of the two?? etc
15:51:29 <acozine> the conversation started with https://github.com/ansible/ansible/pull/74207/files
15:52:13 <acozine> which updated some error messages that were pointing to the pre-2.5 URL for documentation about `become`
15:52:53 <acozine> then bcoca suggested the links should be version-specific, so if you're using Ansible 2.9, you get the 2.9 page about `become`
15:53:35 <acozine> and as samccann and bcoca noticed, it's complicated by the docsite split of `ansible-core` vs `ansible` documentation as well
15:53:54 <abadger1999> Hmmmmmmmmm
15:54:29 <abadger1999> If it was about the website, I'd say it should go to a link on the same website (which I think it will with a relative url) but ansible-doc is more tricky.
15:54:40 <bcoca> roundish , reading
15:54:57 <acozine> unless/until the package can return its own version, as distinct from the underlying ansible-core version, I don't see how we can route these links to the package docs
15:55:22 <abadger1999> ansible-doc probably needs a lot more smarts to do the right thing.
15:55:34 <bcoca> ^ the pr above is mostly for the current cases (2) and to backport, want to make new one if it needs to handle split
15:55:42 <abadger1999> ansible can find out the version of the ansible package and the version of individual collections.
15:55:49 <bcoca> right now 'split' is working with that pr due to redirects
15:55:50 <acozine> in other words, if a user has Ansible 4 installed, the version for `ansible-doc` will be 2.11, but we will not have /ansible/2.11 docs
15:55:55 <acozine> only ansible-core/2.11
15:56:12 <abadger1999> You can get the package version programatically.
15:56:30 <abadger1999> So it is possible to direct to /ansible/3 docs, for instance.
15:56:35 <samccann> keep in mind it also needs to work for Automation Hub and future Galaxy
15:56:39 <bcoca> another option is to have U and L variants or additional params to specify the product/version
15:56:45 <samccann> they grab the same content and display it
15:57:12 <bcoca> but current PR should be enough for now and backport (to non split sites)
15:57:31 <abadger1999> $ python -c 'from ansible_collections.ansible_release import ansible_version; print(ansible_version)'
15:57:56 <acozine> ah, that will return `4` for Ansible 4?
15:57:59 <abadger1999> yep
15:58:07 <abadger1999> well...
15:58:12 <abadger1999> 4.0.0a3 right now.
15:58:28 <abadger1999> But knowing the docsite structure and then trimming off the excess is easy.
15:59:17 * acozine murmurs "just like a regex" and thinks amused and slightly embarrassed thoughts about https://github.com/ansible/ansible/pull/74089
15:59:25 <bcoca> getting the version is not the issue, knowing to which subsite the link belongs is
16:00:02 <abadger1999> What felixfontein suggested in the PR is probably the right thing to  do.  but it requires ansible-doc to make use of more context around the data than it does now.
16:00:22 <acozine> bcoca: if there's a package version, then the link should be `docs.a.c/ansible/<package_version>/.../.../foo.html`
16:00:49 <acozine> if there's not a package version, then the link should be `docs.a.c/ansible-core/<core_version>/.../.../foo.html`
16:00:55 <abadger1999> collections aren't fully understood by ansible-doc.  It takes the data from collections and then mostly pretends like the collections don't exist.
16:01:34 <bcoca> acozine: so ansilbe/ will always have all pages that asnible-core does?
16:02:04 <samccann> cyb-clock sez 61 minutes into meeting, 9 minutes into current topic
16:02:16 * acozine thinks about that question
16:02:24 <samccann> bcoca - no. ansible doesn't have core roadmap for example
16:02:26 <bcoca> abadger1999: ansible-doc loads the specific plugin, colleciton context comes with it, but not really relevant except to display on scr3een
16:02:31 <samccann> someday there could be other differences
16:02:36 <abadger1999> ansible-doc would need to be aware of collections and when it encountered a relative lin, it would need to ask, "what collection is this a part of?   Do we expect that the collection contains that documentation page? If not, do we think the generic docsite will contain it?"
16:02:39 <bcoca> then i need 'more' to know which prefix to use
16:02:44 <acozine> it will always have equivalents at least - it won't have the core porting guides, but it will have porting guides . . . package porting guides
16:02:48 <abadger1999> bcoca: That's exactly the problem.
16:03:01 <abadger1999> bcoca: The "not really relevant"
16:03:20 <abadger1999> This is showing that it has become relevant but ansible-doc doesn't think that it is yet.
16:03:21 <bcoca> for what it needed to display, it wasn't
16:03:32 <abadger1999> Yes... past tense.
16:03:47 <acozine> yeah, for the larger problem of finding the right docs for a specific module in a collection, that is a problem
16:03:48 <bcoca> the changes to split the site just never added ansible-doc, but that is not a limitation as it HAS the context
16:04:16 <acozine> for finding pages about `become`or other core features, it's not
16:04:38 <abadger1999> "it requires ansible-doc to make use of more context around the data than it does now."   and "  It takes the data from collections and then mostly pretends like the collections don't exist."
16:04:55 <bcoca> acozine: at that point the context gets to be counter productive
16:05:24 <bcoca> so we need a way to 'know' the split
16:05:40 <bcoca> as collection context wont give us that for 'non self ref' content
16:05:48 <abadger1999> acozine: this problem gets a lot worse when you prototype moving scenario guides to the collections
16:06:07 <acozine> it sounds like we need to write down all the questions, gotchas, and technical requirements
16:06:16 <samccann> yeah that would help
16:06:56 <acozine> it is complex, and if we all take some time to think through a few more complications, we'll get a better view of the problem(s)
16:07:15 <acozine> abadger1999: yeah, collections-level content is going to be tricky
16:07:17 <bcoca> for now, if everyone ok, i'll merge currenet pr and backport, will fix existing versions
16:07:30 <acozine> though most of the references are likely internal to the collection
16:07:38 <acozine> that may or may not help
16:07:49 <acozine> bcoca: I'd like to look at it again before merging
16:07:53 <bcoca> go4it
16:07:59 <acozine> just to get my head around it
16:08:02 <abadger1999> I think felix's point was that it might not fix it.
16:08:04 <bcoca> thought you had since you added comment
16:08:15 <bcoca> abadger1999: it fixes the issue right now, but not going forward
16:08:24 <acozine> yeah, I did, but i wasn't thinking of the entire bigger picture
16:08:29 <bcoca> and fixing site split, not something we need to backport
16:08:31 <abadger1999> Since we haven't decided whether it should point at /ansible-core/ or /ansible/
16:08:43 <abadger1999> So it could be pointing at the wrong site.
16:08:58 <bcoca> right now it points at ansible and it 'work' for the links we have
16:09:47 <samccann> if the current PR replaces broken links with links to Ansible, it's worth a merge imo
16:10:17 <acozine> yeah, I'm not objecting to it, just want to use this as an opportunity to organize my thoughts a little
16:11:14 <abadger1999> I don't think the code works.
16:11:27 <abadger1999> I think it's still broken.
16:11:35 <samccann> heh woopsie
16:11:42 <acozine> ah, that would be bad
16:11:43 <samccann> cyb-clock sez were over by 11 min
16:11:46 <acozine> heh, yep
16:11:49 <acozine> thanks cyb-clock
16:11:57 <acozine> I think next steps are:
16:12:01 <acozine> testing the PR
16:12:04 <abadger1999> We want  DOCSITE_ROOT_URL  to point to https://docs.ansible.com/ansible right now so that this is a strict upgrade/bugfix right?
16:12:12 <abadger1999> That's currently corret.
16:12:13 <abadger1999> But
16:12:30 <abadger1999> get_versioned_doclink combines that root url with the version of ansible-core.
16:12:41 <abadger1999> It needs to combine the root url with the version of the ansible package.
16:12:53 <samccann> ah yeah.. that needs to happen
16:13:00 <bcoca> agreed, but not for the backport
16:13:02 <abadger1999> otherwise you'll get https://docs.ansible.com/ansible/2.12
16:13:09 <bcoca> and currently the redirects handle the 2 cases we have
16:13:10 <abadger1999> which is going to be a 404
16:13:52 <bcoca> why we need another PR to handle the versions that the split site doesn't redirect
16:14:25 <acozine> I'll volunteer to do a write-up of the use cases
16:15:12 <acozine> and post a link here
16:15:26 <acozine> after the meeting
16:15:59 <samccann> cool thanks!
16:16:02 <acozine> then if the current PR addresses at least one use case, we'll have that one fixed and a roadmap for the rest of the necessary work
16:16:10 <acozine> okay, 1 hour 15 minutes
16:16:21 <acozine> other topics for open floor?
16:16:27 <acozine> PRs to review?
16:16:33 <acozine> issues that need attention?
16:16:41 <acozine> comments, questions, suggestions?
16:18:01 <acozine> thanks abadger1999 bcoca dmsimard felixfontein  dericcrago kindlehl lmodemal samccann
16:18:11 <acozine> and anyone who was lurking and listening!
16:18:12 <lmodemal> nothing for me :)
16:18:43 <acozine> see you here next week, one hour earlier, for the Mini Docs PR Review Day
16:18:51 <acozine> #endmeeting