15:01:05 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:05 <zodbot> Meeting started Tue Mar 29 15:01:05 2022 UTC.
15:01:05 <zodbot> This meeting is logged and archived in a public location.
15:01:05 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:05 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:05 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:22 <samccann> #topic opening chatter
15:01:30 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:54 <briantist> o/
15:01:55 <acozine> o/
15:01:58 <briantist> (very distracted)
15:02:03 <samccann> andersson007_: briantist   yo uareound for docs fun
15:02:04 <felixfontein> o/
15:02:18 <samccann> #chair acozine felixfontein briantist
15:02:18 <zodbot> Current chairs: acozine briantist felixfontein samccann
15:02:43 <acozine> I am actually not double-booked. It's a nice feeling.
15:02:55 <samccann> lol yeah monotasking FTW
15:03:08 <samccann> All are welcome! Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
15:03:24 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1068258251
15:03:41 * samccann ponders how often we actually follow the official agenda...
15:04:15 <acozine> heh, possibly never
15:04:22 <samccann> heh yep
15:04:24 <samccann> #topic Documentation updates
15:04:35 <acozine> I was wondering how long it's been since we did a retrospective on Action Items
15:04:51 <acozine> I feel like I might have some still "hanging"
15:04:52 <samccann> most of them are done. I have a few lingering
15:05:11 <acozine> most of them are DONE? wow, that's awesome
15:05:39 <samccann> there's this one
15:05:40 <samccann> @samcann acozine - to review Confusing ansible-test cli help ansible#76609 in terms of how we can add to the cheatsheet and/or create split controller docs to help out here (and eventual URL added to ansible-test --help1 output
15:06:04 <samccann> pointing to https://github.com/ansible/ansible/issues/76609
15:06:48 * gwmngilfen-work is kinda here, just got out of a mtg
15:06:49 <samccann> #info one old action item to review https://github.com/ansible/ansible/issues/76609 in terms of how we can add to the cheetsheet and/or create split controller docs to help out here (and eventual url add to ansible-test --help output)
15:06:58 <samccann> #chair Gwmngilfen
15:06:58 <zodbot> Current chairs: Gwmngilfen acozine briantist felixfontein samccann
15:07:02 <samccann> welcome welcome
15:07:31 <acozine> Gwmngilfen: have you seen https://github.com/ansible/ansible/pull/77352?
15:08:15 <gwmngilfen-work> i did not. Lets add it to the AOB so as not to interrupt
15:08:25 <acozine> heh, sorry
15:08:41 <samccann> AOB?
15:08:56 <gwmngilfen-work> any-other-business
15:09:01 <samccann> oh hahaha ok
15:09:05 <samccann> meanwhile...
15:09:15 <samccann> #info proposed Docs priorities for the coming 18 months or so - https://github.com/ansible-community/community-topics/issues/81
15:10:18 <samccann> comments and feedback most welcome. This is what feels like the right priority but i'd love community advice here in case I'm missing something important.  They are roughly listed in order
15:11:26 <samccann> #info  next emphasis on 'getting started' guides - focusing on new users, contributors, developers.
15:12:42 <samccann> #info stable-2.13 branch pulled. Doing docs backports weekly until Ansible 6 releases.
15:13:10 <samccann> #topic Pip only install docs
15:13:17 <samccann> #info stable-2.13 branch pulled. Doing docs backports weekly until Ansible 6 releases.
15:13:55 <samccann> I'd say that topic had some interesting feedback, but my  TL;DR; is we probably need a 'other install options' page  that would link to any known install instructions for other repos
15:14:08 <samccann> And a place for PPA installs if we need them.
15:14:36 <acozine> where did the feedback come from / go to?
15:14:51 <acozine> I think you're right, I'd be interested in reading what others wrote about the change
15:15:38 <samccann> The feedback is in comments on the issue
15:16:04 <samccann> oh sorry, had my posts in funky order.  The feedback wasn't on stable-2.13, it's on install via pip only in the docs
15:16:24 <samccann> #info docs install trimmed to pip only - https://github.com/ansible-community/community-topics/issues/83 -
15:16:25 * acozine digs around for a link
15:16:26 <samccann> there
15:16:27 <samccann> sorry lol
15:16:28 <acozine> ah, thanks
15:16:48 <samccann> that's what I get for trying to prep for the meeting and have some infos in a file I can just copy/paste here
15:17:45 <samccann> any comments on pip install docs or should I move on?
15:18:19 <acozine> I loved the comment from briantist `no matter how bad of an idea it is people will still want to do it,`
15:18:25 <acozine> yes, yes they will
15:18:37 <gwmngilfen-work> 💯
15:18:55 <samccann> heh
15:19:43 <samccann> what gave me the 'ahah' moment - pip install ansible has unpinned requirements. So it's not just ansible that might be brought in, so to speak, but a bunch of dependencies etc
15:20:08 <acozine> yep, that's why we adopted the `known_good` thing for the docs build
15:20:09 <felixfontein> yes. same is true for `pip install ansible-core`
15:20:32 <acozine> so we would have repeatable, reliable versions of dependencies
15:21:15 <samccann> so I think my action item then is to create an 'other installation options' page with links to any distros that have ansible install instructions for their OS or something.  Or at least a template page to say 'we'll accept PRs here but cannot guarantee the content'
15:21:15 * acozine is freezing, going to grab a warmer sweater
15:21:48 <samccann> It's still garnering comments so I won't act immediately, but that's where I'm leaning
15:22:03 <gwmngilfen-work> makes sense
15:22:22 <samccann> #topic Ending devel-only docs
15:22:34 <samccann> #info seems unpopular that we have a few docs only on devel. Starting in 2.13 as latest, we will stop this trend and go back to keeping porting guides and release/maint pages up to date in lateset and devel. Will not be going to older releases.
15:22:58 <felixfontein> oh, so return of the backport pain?
15:23:54 <felixfontein> including not being able to update the stable docs when ansible-core has RC freeze week?
15:24:19 <samccann> ^^ will also grow to include the community guide(s) since they are really unversioned as well
15:24:20 <samccann> aka samcann gonna be backporting herself into a stupor
15:24:20 <samccann> #info longer term, we'll investigate an unversioned approach, per comments in - https://github.com/ansible-community/community-topics/issues/68
15:24:20 <samccann> so if we can find a way to say 'go grab these files from this repo and add them here' before make webdocs etc happens, that would solve this I think
15:24:20 <samccann> but no idea how to do ^^ w/o git submodules which I hear are the spawn of the devil
15:25:42 <gwmngilfen-work> submodules aren't so bad
15:25:53 <gwmngilfen-work> but the learning curve is nasty
15:25:56 <samccann> felixfontein: yep. And we were really cutting it down to the wire with the antsibull version updates yesterday on branch day. Unrelated to versioned/unversioned docs, but related to being tied to ansible/ansible branching etc
15:26:23 <samccann> I think if I tried submodules in ansible/ansible to get this done, I'd be put in the Ansible stocks for a week
15:27:11 <samccann> one thing I just realized is NOT on the docs priority I pointed to earlier is all of this.
15:27:24 <samccann> which means.. erm.. we won't solve it in the next 2 yrs
15:27:29 <felixfontein> submodules don't really help, since you still have to update the submodule in that branch
15:27:48 <felixfontein> pulling the files from another repo on build time is probably the best solution
15:28:01 <samccann> yeah, that's what I'd want
15:28:02 <felixfontein> (obviously that kills the ability to version this stuff...)
15:28:43 <samccann> is there anything obvious /already done somewhere else/ that pulls files from another repo on build time?
15:28:44 <acozine> well, if it gives us the ability to publish it only on `latest`, I'd say that's a fair tradeoff
15:29:17 <samccann> updating submodules in latest might be as time consuming as just backporting, but I could be wrong
15:29:53 <felixfontein> probably a bit less, but probably not that much that it's really worth the additional hassle
15:30:08 <acozine> the trouble is, if you backport everything into latest, then when a new version comes out, you have to delete that stuff from the no-longer-latest branch
15:30:21 <samccann> nope, will NOT be doing that
15:30:51 <samccann> I am willing to sign up to backport hell, but not stubb-hell when a version goes older than latest
15:30:57 <acozine> heh
15:31:07 * samccann will probably regret saying that
15:31:54 <samccann> mind you if we had that archive site for docs, that would help a little. But again, not on the docs priority list so.. probly not happening
15:33:50 <samccann> ok added them as comments to the docs priority
15:34:10 <samccann> I've probably wailed and gnashed my teeth enuf on this for one meeting.
15:34:18 <samccann> #topic doctools
15:34:34 <gwmngilfen-work> should you ever need submodules, let me know, I have ... history :)
15:34:41 <samccann> lol ok good to know
15:35:31 <samccann> #info we have buttons and extra links on collection pages now! https://docs.ansible.com/ansible/devel/collections/community/dns/index.html
15:35:43 <acozine> hooray!
15:36:00 <gwmngilfen-work> felixfontein++
15:36:06 <samccann> much thanks to felixfontein and Gwmngilfen for getting this out the door in time for Ansible 6/ core-2.13!!
15:36:08 <acozine> that was a long time coming, and it looks great!
15:36:21 <briantist> 🎉great work on that!
15:37:42 <briantist> I'm still pretty demoralized on continuing work with docs-build due to this issue, no response from GitHub still, even with gundalow emailing them (not sure if he heard back from the last email at all), I don't know what to do anymore. https://github.community/t/called-workflows-cannot-be-queued-onto-self-hosted-runners-across-organisations-enterprises-failed-to-queue-this-job-labels-ubuntu-latest/229355?u=briantist
15:38:15 <gwmngilfen-work> 😢
15:38:57 <acozine> they've been having stability issues with GitHub Actions, don't know if that plays into their response to ^^^
15:39:22 <samccann> dang that's a downer for sure
15:39:33 <acozine> (or non-response, I guess)
15:40:36 <acozine> it's frustrating briantist sorry they're stonewalling this work
15:40:38 <samccann> is there any interim approach we could use instead? Create a tool that would run the docs build outside of github so collection owners could at least run it locally and find errors?
15:40:42 <briantist> the guy gundalow emailed responded to the issue initially ("we'll look into it" basically), but from then, nothing
15:41:11 <briantist> well, they can already run things locally, but this project is entirely github workflows and actions
15:41:30 <briantist> the only workaround I can think of is to move the docs-build repo into the `ansible-collections` org
15:41:49 <briantist> that would only work around it for collections in that org, not for any outside of it
15:42:03 <gundalow> briantist: nop, not heard anything more. Can work around it, move repo, throw money at the problem?
15:42:50 <briantist> ironically money can't solve this problem, it's a bug they seem unwilling to fix, probably because it doesn't affect enough users
15:42:53 <samccann> ansible-collections lists 106 repos. I know not all are collections, but sounds like it would help a lot of collections if we could move?
15:43:24 <briantist> it might, but it's a band-aid
15:43:41 <briantist> I'm also assuming it would work based on the error message..  so not certain
15:44:25 <briantist> hm, another workaround is not to use the reusable workflows, or to copy/duplicate them to every repo that wants to do docs build
15:45:20 <briantist> maybe I'll consider that in the meantime
15:45:36 <samccann> I don't know enough about it all to comment on which workaround option might be best to consider
15:46:22 <samccann> that would be great! I realize it's demoralizing to hit a dead end on the current approach for sure.
15:47:50 <samccann> ok gonn open the floor
15:47:56 <samccann> #topic Open Floor
15:48:05 <samccann> Now's the time to bring up anything else in docs land on your mind!
15:49:05 <gwmngilfen-work> acozine: so that issue
15:49:46 <gwmngilfen-work> the reporter isn't wrong per se, both aliases will work (this room is reachable at docs:ansible.com and docs:ansible.im)
15:50:35 <gwmngilfen-work> the nuance is (in my mind) that .com denotes something official, covered by the CoC etc - becausewe (the community team) manage those aliases. Anyone with an ansible.im account can create .im rooms/aliases
15:50:51 <gwmngilfen-work> so, it's not fatal but it should probably be updated, yes
15:51:04 <acozine> gotcha
15:51:14 <acozine> I think we have links to *.im in a lot of places
15:51:30 <gwmngilfen-work> likely. it was built before we got the ability to add .com aliases
15:51:40 <samccann> #info https://github.com/ansible/ansible/pull/77352
15:51:47 <gwmngilfen-work> and you & I did the initial update of the docs fairly soon after the community vote
15:52:36 <acozine> ah, i didn't realize something had changed there
15:52:42 <acozine> yes, we updated those pretty quickly
15:53:36 <samccann> so the PR is correct and we should review/merge? and look out for any other .im links and change to .com?
15:54:11 <gwmngilfen-work> we probably to check the aliases are present (they should be, from a quick skim), in generally, yes
15:54:15 <gwmngilfen-work> *want to
15:54:49 <gwmngilfen-work> we may also want to spell out the .com/.im policy somewhere to prevent more confusion
15:55:05 <gwmngilfen-work> tbh, I'd prefer to just direct people to the Space, but that doesn't work for IRC ofc
15:55:25 <gwmngilfen-work> (because it's easier to keep the Space up to date, and you don't care about the aliases then)
15:55:40 <gwmngilfen-work> the new extra-links stuff will reduce reliance on this page over time, too
15:55:49 <acozine> the page from the PR seems like hte right place to "spell out the .com/.im policy"
15:55:55 <acozine> the Communicating page
15:56:10 <acozine> most of the other Matrix links are in `See also` IIRC
15:57:47 <samccann> the docs links used on collection pages uses im and I think it's too late to change that for 2.13/Ansible 6
15:59:05 <gwmngilfen-work> it's not critical, I think - that it hasn't come up sooner suggests most people aren't too worried. but we should fix it when we can
15:59:40 <samccann> ok
16:00:11 <samccann> Any other open floor topics before we end the meeting?
16:01:12 <acozine> can't think of anything
16:01:18 <samccann> #endmeeting