15:59:21 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:59:21 <zodbot> Meeting started Tue Feb 22 15:59:21 2022 UTC.
15:59:21 <zodbot> This meeting is logged and archived in a public location.
15:59:21 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:59:21 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:59:21 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:59:34 <samccann> #topic opening chatter
15:59:49 <samccann> @room Meeting time! Who is here to talk the docs?
16:00:02 <samccann> 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!
16:00:49 <briantist> o/
16:00:55 <samccann> andersson007_: briantist tadeboro cyberpear - you around to talk docs
16:00:59 <samccann> hah! beat me too it!
16:01:05 <samccann> #chair briantist
16:01:05 <zodbot> Current chairs: briantist samccann
16:01:26 <briantist> am in a different meeting, and double plus booked with other things (as usual haha)
16:01:36 <samccann> lol yep
16:01:37 <amott[m]> o/
16:01:46 <samccann> #chair amott
16:01:46 <zodbot> Current chairs: amott briantist samccann
16:01:50 <samccann> welcome welcome!
16:02:50 <gwmngilfen-work> i'm here for the first 20min or so
16:02:56 <samccann> #chair Gwmngilfen
16:02:56 <zodbot> Current chairs: Gwmngilfen amott briantist samccann
16:03:04 <samccann> #topic doctools
16:03:24 <samccann> we'll go into tooling stuff first today then. Got any updates Gwmngilfen on the link/buttons PR etc?
16:04:26 <samccann> #link https://github.com/ansible-community/antsibull/pull/355
16:04:53 <gwmngilfen-work> I've done a quick review, as you have I think. felixfontein has responded earlier today, so I need to go think about that
16:06:49 <samccann> yep cool. I think what we could quickly chat about - do we need all the buttons on each module page, or what felix said in the note - if you scroll to the bottom of a module page there is a note there on how to edit https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_module.html#authors
16:07:17 <gwmngilfen-work> every page load is going to lose some users, people are flaky :P
16:07:27 <gwmngilfen-work> so I would argue for keeping all the buttons
16:07:57 <gwmngilfen-work> that said, I don't think we need #users:ansible.com / #ansible on every page, that will get very repetetive
16:08:12 <samccann> #info open question - do we want all buttons on all module pages, or just the current 'click here to edit' that the current examples have
16:08:15 <gwmngilfen-work> so in theory it's not likely to exceed 5 links at most
16:08:46 <gwmngilfen-work> ofc a collection owner could abuse that, but they're only going to confuse their own users, so that's on them :P
16:09:48 <samccann> So the existing 'edit' link really is like the old Edit on GitHub, which is nice. I can click (assuming I've already forked the repo) and make a quick PR.
16:10:38 <gwmngilfen-work> right, the intention is to get users to the next place they want to be quickly.
16:11:08 <gwmngilfen-work> as to where on the page the buttons should be, I'm not the best person to answer that - I'm not good at UI :P
16:11:14 <samccann> ok so I'm happy with the existing functionality on the module page, but when you get a chance, add your ideas to the PR please
16:11:23 <gwmngilfen-work> I will, yes
16:12:08 <samccann> amott: you might have an interesting perspective here, as someone not necessarily writing code but maybe wanting to report a problem on a module?
16:12:51 <amott[m]> I've actually joined in as I saw the quick fix links and was going to see what I can do there :)
16:13:47 <gwmngilfen-work> yes! very interested in end-user feedback. for context, I'm looking at things like https://www.home-assistant.io/integrations/esphome/ and realising that they do a good job of giving users one-click directions to the next thing they might want to do
16:14:39 <amott[m]> From using the docs a lot though, I've not had any issues  with navigation or thought there were too many links (I presume you men the breadcrumb links at the top?)
16:14:55 <samccann> #info we're looking at https://www.home-assistant.io/integrations/esphome/ for inspiration on these links/buttons. Goal is to make it as easy as possible for someone to contribute/open an issue against modules and plugins
16:15:00 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:15:28 <gwmngilfen-work> it's more that every collection could potentially have it's own github, discussions, and chat rooms - so we want to get people to the right place to contribute or ask things
16:15:44 <samccann> yeah so look here to see the collection top page - https://ansible.fontein.de/collections/community/dns/index.html
16:15:52 <samccann> and notice the row of buttons and links to chat etc
16:16:44 <samccann> and then at the bottom of a module page, there is an edit link - https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_set_module.html#return-values
16:17:05 <samccann> The current debate is - should we move all the buttons to the module page as well or is the edit button enough
16:18:36 <amott[m]> I see no Edit button, nor any links to chat...
16:18:36 <amott[m]> That page looks quite sparse TBH, with the blue/green issue tracker, repo etc buttons stukc out on their own to one side
16:19:02 <acozine> o/
16:19:19 * acozine reads the backscroll
16:21:59 <samccann> So on the page with the button, that page itself cannot directly be edited (thus no obvious edit button), if you click any module or plugin and scroll to the bottom you see the note about editing the page with a link
16:22:23 <acozine> I do kinda wish we could get that `edit` button up to the upper right corner of the page
16:22:53 <acozine> amott: welcome to the Docs Working Group, aka DaWGs!
16:23:04 <gwmngilfen-work> it is where people tend to look for that sort of thing now
16:23:30 <amott[m]> That edit link is REALLY easy to miss!
16:23:52 <acozine> amott: the other buttons show up here, on the collection's main docs page: https://ansible.fontein.de/collections/community/dns/index.html#plugins-in-community-dns
16:24:06 <acozine> Issue Tracker, Repository, Submit a bug report, etc.
16:24:35 <acozine> I agree that the edit link is easy to miss
16:24:44 <acozine> at least it exists!
16:25:05 <samccann> I'm adding notes directly to the WIP PR to capture what we are saying here btw
16:25:08 <acozine> but with a little ingenuity maybe we can make it easier to find
16:25:22 <amott[m]> Those other buttons appear to be centred on the page, which looks odd when the rest is left-justified.
16:25:26 <amott[m]> Especially on a large screen!
16:25:45 <acozine> true
16:25:58 <gwmngilfen-work> see, this is why I don't do UI design
16:26:05 <gwmngilfen-work> I hadn't even noticed
16:26:44 <acozine> The section headings in the left nav are blue, instead of the Ansible "lake" (teal), too
16:27:14 <acozine> Gwmngilfen: count your blessings, sometimes noticing that stuff can be . . . well, something between a distraction and a curse
16:27:40 <gwmngilfen-work> https://en.wikipedia.org/wiki/Aphantasia
16:27:44 <samccann> Felix is asking in the PR - where do we want the buttons on the module page? Since we are talking five buttons, do we want  them in a new section maybe called feedback?"
16:28:12 <gwmngilfen-work> gotta go to another meeting, I will leave UI design in your capable hands ;)
16:28:18 <samccann> acozine: that's just Felix's test site. It's not the full ansible theme he uses.
16:28:32 <samccann> But I would 'guess' the buttons will look the same on the real theme as they look today
16:28:43 <acozine> Bye, Gwmngilfen!
16:28:48 <samccann> Thanks Gwmngilfen
16:28:57 <gwmngilfen-work> thanks for the input everyone!
16:29:04 <gwmngilfen-work> (and ofc thanks to felix for all the work)
16:29:23 <acozine> I wonder if we could have a second header section on the module pages
16:29:38 <acozine> under the breadcrumbs, above the title
16:30:00 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:30:02 <acozine> put the buttons there?
16:30:18 <acozine> maybe add the Edit link at hte right?
16:30:28 <acozine> I say this, with no idea whether it's possible or how much work it would be
16:30:28 <samccann> worth asking about anyway
16:31:27 <samccann> ok anything else on this before we move on?
16:31:44 <acozine> it's a big step forward
16:32:06 <acozine> we should be ready to edit the page on editing docs, too, when this is ready to merge
16:32:18 <samccann> yep
16:32:24 <acozine> "to edit collections docs, look for . . ." whatever it ends up being
16:33:02 <samccann> #action samccann to have a PR for how to edit collection docs once https://github.com/ansible-community/antsibull/pull/355 merges
16:33:19 <samccann> Ok moving on
16:33:24 <samccann> #topic unversioned docs
16:33:38 <samccann> #info community-topic to discuss if we want to have unversioned docs (like community/contributor guides) - https://github.com/ansible-community/community-topics/issues/68  Please add your comments there.
16:34:23 <samccann> The point being - we have a small subset of docs that are not specific to a release, but our current publishing options demand a release. That topic lays out three options and some pros n cons (and it's probably not the full ideas)
16:34:44 <samccann> Hoping to garner feedback and we've had a lot of luck in the past with people async posting to topics so... hoping for that ;-)
16:34:50 <acozine> I've been thinking about this off an on, and coming around to . . most of those docs belong in `latest` and only in `latest`
16:35:15 <briantist> (and/or `devel` though)
16:35:25 <acozine> though the porting guides will also need to live in devel
16:35:35 <acozine> hey briantist!
16:35:50 <samccann> yeah that's even HARDER to do (latest only) as it breaks the current backport paradigm ansible core follows
16:36:21 <acozine> I don't think it's possible unless those docs live in a separate repo
16:36:46 <acozine> but there's been a lot of interest in moving them for other reasons
16:37:18 <samccann> even so, it means 'whatever magic' pulls those files in, can only pull them in for latest. Said magic script couldn't exist in devel and would have to be removed from the appropriate release branch after that release is no longer latest
16:37:48 <acozine> I'm assuming the script/code/whatever would live in antsibull
16:37:49 <samccann> but can you also add your thoughts to that communit-topic when you get a chance?
16:38:18 <samccann> Felix was saying nope for ansibull, that the script should live in core
16:38:28 <samccann> (ansible/ansible) with the other docs scripts.
16:38:29 <acozine> ah, then maybe it's a pipe dream
16:39:05 <samccann> still worth adding your comments to the topic.
16:39:21 <acozine> okay, I'll do that this week
16:39:26 <samccann> someone probably knows a way of doing it once we decide what 'it' is
16:39:33 <samccann> cool, thanks!
16:40:16 <samccann> Ok gonna move to docs updates next
16:40:21 <samccann> #topic documentation Updates
16:40:32 <briantist> I did have a quick doc tools update
16:40:34 <samccann> #info crafting better changelog fragments PR - ttps://github.com/ansible/ansible/pull/77040
16:40:34 <samccann> needs reviews
16:40:39 <samccann> woopsie
16:40:48 <samccann> go for it briantist
16:41:06 <briantist> it's only that I've run into an issue with GitHub reusable workflows: 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
16:41:25 <acozine> have they responded at all?
16:41:45 <briantist> it would affect anyone using the docs build who also has contention in the GitHub workflows, so especially collections like mine that use GHA for CI
16:41:51 <briantist> they have not responded at all
16:42:11 <acozine> hm, that's too bd
16:42:14 <acozine> * hm, that's too bad
16:42:24 <briantist> I've asked gundalow if it would be possible to engage GitHub support, not sure if he was able to do that
16:42:59 <samccann> that's a bummer!
16:43:11 <briantist> anyway, that's all I got, would appreciate people adding likes or "me too"s as appropriate
16:45:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:45:04 <samccann> added my 'me  too' approach since this is holding up the docs build PRs :-)
16:45:26 * samccann must remember a better name for this feature
16:45:38 <samccann> anyway thanks for keeping at it briantist !!
16:45:42 <briantist> thx
16:46:14 <samccann> so the only new docs update is I need feedback on the crafting better changelog fragments - vector://github.com/ansible/ansible/pull/77040
16:46:32 <samccann> so I can get it merged etc. This would close out the match community-topic discussion from a couple of weeks back.
16:47:11 <acozine> heh, I just opened that link and i have a Pending reivew
16:47:13 <acozine> s/reivew/review/
16:47:23 <acozine> sorry, I'll get it finished
16:47:53 <samccann> hehe
16:47:56 <samccann> thanks!
16:47:56 <acozine> briantist: I put a "me too" comment on your community bug report
16:48:04 <briantist> thx
16:48:28 <samccann> ok we have some time left for an open floor
16:48:34 <samccann> #topic Open Floor
16:49:06 <samccann> Now's the time to bring up anything else in and around docs that we haven't covered. Got a burning question? A PR that's stalled? here's the time to bring it up!
16:49:41 <acozine> amott: how did you find out about today's meeting / what brought you to the channel?
16:50:19 <acozine> it's great to see new . . . I guess I can't say "faces", but new folks joining the chat!
16:51:40 <amott[m]> I was just about to say that I'd like to help with the quick fix issues (found in the Bullhorn a couple of weeks ago), and I've been in the channel since then, mainly lurking.
16:51:40 <amott[m]> I could do with a basic run-through of how to get started, or a pointer to docs - I'm new to collaborative/development/git stuff so tips and pointers would help me get started
16:51:57 <amott[m]> I knew about today's meeting because the remindbot told me :)
16:52:08 <acozine> Bullhorn and remindbot for the win!
16:52:12 <samccann> woot for remindbot!
16:53:03 <acozine> there's a page in the docs about contributing to docs: https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#community-documentation-contributions
16:53:44 <acozine> that should give you a first introduction - and please as you read it, make notes about what you'd like to see that ISN'T there
16:54:24 <acozine> new contributors are absolute gold, because "old hands" who've contributed before have forgotten what it's like to contribute for the first time
16:54:33 <acozine> so we make a lot of assumptions and leave things out
16:55:01 <amott[m]> Ok, I'll take a bit of time and read through that. Stand by for notes... (I guess in the next meeting?)
16:55:09 <acozine> that would be awesome
16:55:20 <samccann> you can always pop in here and ask questions, comment etc
16:55:26 <acozine> chat is welcome in channel/room any time
16:56:17 <acozine> what kinds of stuff are you doing with Ansible?
16:58:53 <amott[m]> Cool, I'll try to ask when I'm confused.
16:58:53 <amott[m]> I do all sorts - lately been a lot of provisioning stuff, with Tower, Satellite, VMware, Azure etc.
16:58:53 <amott[m]> Creating workflows in Tower, stringing together playbooks and roles to build and configure systems. New disks in VMware, new LVM configs, all the ususal stuff
16:59:12 <acozine> sounds great
16:59:48 <amott[m]> I guess Ansible is 30% or more of my job
16:59:54 <amott[m]> Lots of fun :)
17:00:27 <acozine> yep
17:01:15 <samccann> ok probably time to end the meeting
17:01:20 <samccann> #endmeeting