18:31:00 <bcotton> #startmeeting docs
18:31:00 <zodbot> Meeting started Wed Aug  3 18:31:00 2022 UTC.
18:31:00 <zodbot> This meeting is logged and archived in a public location.
18:31:00 <zodbot> The chair is bcotton. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
18:31:00 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
18:31:00 <zodbot> The meeting name has been set to 'docs'
18:31:09 <bcotton> #topic Roll call
18:31:11 <pboy> .hi
18:31:12 <zodbot> pboy: pboy 'Peter Boy' <pboy@uni-bremen.de>
18:31:32 <py0xc3[m]> .hello py0xc3
18:31:33 <zodbot> py0xc3[m]: py0xc3 'Christopher Klooz' <py0xc3@my.mail.de>
18:31:34 <bcotton> #chair pbokoc, bcotton, darknao, pboy
18:31:34 <zodbot> Current chairs: bcotton darknao pbokoc pboy
18:31:39 <darknao> .hi
18:31:40 <zodbot> darknao: darknao 'Francois Andrieu' <darknao@drkn.ninja>
18:31:47 <hankuoffroad[m]> .hello hankuoffroad
18:31:48 <zodbot> hankuoffroad[m]: hankuoffroad 'None' <allegrovelo@gmail.com>
18:31:57 <bcotton> welcome, welcome, everyone
18:32:03 <py0xc3[m]> hi!
18:33:58 <darknao> hey :)
18:33:59 <bcotton> #topic Agenda
18:34:07 <bcotton> #info Announcements
18:34:07 <bcotton> #info Review action items
18:34:07 <bcotton> #info Internal docs organization
18:34:07 <bcotton> #info Open floor
18:34:14 <bcotton> #topic Announcements
18:34:23 <bcotton> #help Some release notes still need written: https://discussion.fedoraproject.org/t/how-to-write-fedora-release-notes/38311
18:34:31 <bcotton> #info Nest With Fedora starts tomorrow: https://hopin.com/events/nest-with-fedora-2022
18:34:40 <bcotton> #info Anushka Jain will have a talk
18:34:49 <bcotton> #info Share the Docs survey with your friends: https://fedoraproject.limequery.com/826569
18:34:56 <bcotton> #info We're using the docs-fp-o repo to track meta-work
18:34:56 <bcotton> #link https://pagure.io/fedora-docs/docs-fp-o/issues
18:35:05 <bcotton> (we should probably update this to gitlab now, eh?)
18:35:14 <bcotton> anything else anouncementy?
18:35:36 <bcotton> #topic Previous action items
18:35:39 <bcotton> #info pboy to update the team page regarding board and members
18:36:03 <pboy> Sorry, not yet.
18:36:12 <pboy> I am busy consolidating 14 Fedora servers to a smaller number
18:36:15 <bcotton> #action pboy to update the team page regarding board and members
18:36:26 <bcotton> sounds like a worthy goal :-)
18:36:28 <py0xc3[m]> Can I help pboy ?
18:36:48 <pboy> Unfortunately, I'm alone with my team
18:36:59 <pboy> All the little sins of the past are now coming up again
18:37:21 <pboy> and cost a crazy amount of time
18:37:43 <bcotton> I understand that
18:38:16 <bcotton> #topic Internal docs organization
18:38:16 <bcotton> #link https://discussion.fedoraproject.org/t/internal-docs-organization-gitlab-workflow-process-organization/40819
18:38:33 <bcotton> so i didn't have a chance to read the full log, but from the minutes i understand that this conversation needed to continue this week?
18:39:04 <pboy> yes, also I'm a bit lost as well.
18:39:28 <py0xc3[m]> We added the "triage" category, and another question was about the "good first issue" category, but I think there is an issue about the latter: https://discussion.fedoraproject.org/t/internal-docs-organization-gitlab-workflow-process-organization/40819/9
18:40:27 <py0xc3[m]> I am not able to make use of this possibility, to assign to externals, darknao is that something dedicated to people with Owner rights?
18:40:33 <darknao> about the assignement?
18:40:59 <bcotton> in my experience "good first issue" is used to indicate a relatively easy/simple issue for newcomers to work on, so that label is added by maintainers
18:41:13 <bcotton> this is what, for example, HacktoberFest recommends
18:41:27 <darknao> yeah, I think we can only assign issue to people that are participating to the discussion (and group members)
18:41:47 <darknao> since newcomers usually comment on such issue to request assignement, that should not be an issue
18:41:57 <py0xc3[m]> I do not see an issue with the category, we just have to be aware that the job gets done at some point, even if there is no external to take it up. The remaining issue would be how to assign externals.
18:41:57 <darknao> but we need to confirm that
18:42:38 <hankuoffroad[m]> py0xc3[m]: I made a suggestion to label "good first issue" in GitLab, so contributors can self-assign
18:43:01 <darknao> contributors can't "self-assign"
18:43:07 <darknao> they need to ask for it
18:43:15 <py0xc3[m]> hankuoffroad[m]: I would suggest to change the name, as I think many link "good first issue" to something else.
18:43:16 <darknao> only group members can assign people
18:43:34 <darknao> good first issue is the right name in my opinion
18:43:37 <hankuoffroad[m]> okay
18:43:38 <darknao> it's used everywhere
18:43:47 <py0xc3[m]> Yes but for a different purpose
18:44:00 <hankuoffroad[m]> pagure uses that as well.
18:44:09 <py0xc3[m]> I opened an issue at a external repo. As it was good formulated, it was assigned "good first issue" by the maintainer.
18:44:29 <bcotton> py0xc3: i have never seen the label used that way
18:44:30 <darknao> https://goodfirstissue.dev/
18:44:52 <darknao> that's an example
18:45:02 <bcotton> i'm not saying it doesn't get used that way, but that's not the common usage
18:45:15 <darknao> or https://github.com/topics/good-first-issue
18:46:05 <py0xc3[m]> Well, I didnt know that use case tbh :D But if there are several experiences here that this is the usual use of it, I will not oppose :)
18:46:20 <darknao> but I'm not against using another name if you prefer, there is no hard rules about this kind of tag
18:47:04 <py0xc3[m]> But how to handle it, if someone takes it up? I would say, one of us takes the supervision (=assignee) and the remaining is done in the comments?
18:47:12 <py0xc3[m]> As we cannot assign externals
18:47:39 <hankuoffroad[m]> darknao: that's no problem to reword it.
18:48:07 <darknao> we can use "easyfix" instead if it's sounds better
18:48:21 <py0xc3[m]> darknao: No objection from my side. I just linked "good first issue" to something else. But if you all agree that this is the usual meaning, it makes sense to stick with that
18:48:26 <darknao> py0xc3[m]: we can assign externals
18:48:57 <py0xc3[m]> darknao: I cannot. Even externals that have successful merge requests cannot be assigned by me
18:49:14 <darknao> I've seen way more than just group members in the assignees box
18:49:16 <py0xc3[m]> I can only choose between those who are already in the group
18:49:34 <darknao> I think they needs to be active participant of the discussion for that
18:49:50 <darknao> like just post a comment in the ticket, and they will appear in the assignee list
18:49:57 <py0xc3[m]> Maybe this is an owner thing? I can add the roughly 20 people in the group. But even computersavvy and my non-FAS account cannot be assigned, although both submitted already MR
18:50:28 <py0xc3[m]> darknao: Ah, ok. That makes sense. I'll check
18:51:17 <darknao> let us know of the results
18:51:39 <bcotton> so it sounds like there's a general agreement on this and we just need to work out a few implementation details?
18:53:12 <bcotton> since no one objects...
18:53:27 <pboy> I agree, but
18:53:32 <bcotton> go ahead
18:53:40 <pboy> I am concerned whether we are now regulating in too much detail as a first step and that might be more of a deterrent.
18:54:00 <pboy> Bet old Unix priciple: KIS
18:54:08 <pboy> Betg -> Better
18:54:28 <bcotton> that's a valid concern
18:54:43 <py0xc3[m]> Maybe just do what we agreed already last week, and just add the good first issue without starting to regulate it?
18:54:46 <py0xc3[m]> And see how it develops?
18:55:24 <pboy> Or we complete the intentions, so far, and then try to find a kind of compressed or simplified version.
18:56:51 <pboy> I think I'm used to read quite complex texts. But this is not easy.
18:57:21 <pboy> Specifically new contributors may have problems.
18:57:21 <py0xc3[m]> What exactly do you mean? In general or the good first issue thing?
18:57:32 <pboy> More in general.
18:57:50 <pboy> There seem to be too much steps.
18:58:37 <pboy> Although I am convinced, we need a systematic approach.
18:58:44 <darknao> pboy: new contributors don't need to know anything about this, it's only us (as group members) that needs to add the required labels, if needed
18:58:49 <py0xc3[m]> Maybe keep the discussion open, shift it to next week, and focus the debate on compressing it? Or I could merge the ideas we added and create a new thread, to then discuss how to compress
18:59:03 <bcotton> how about this
18:59:14 <bcotton> let's start with what we have now, use it a while, and see where the friction is
18:59:29 <darknao> +1
18:59:33 <pboy> I'm fine with that.
18:59:42 * osezer[m] says hello and find a chair to sit and start listen the meeting.
18:59:44 <hankuoffroad[m]> i concur
18:59:48 <bcotton> we can discuss the hypothetical aspects of it forever, but we won't know where it's truly broken until we use it :-)
18:59:52 <darknao> \o osezer[m]
18:59:54 <py0xc3[m]> Me, 2. +1 . But including or excluding the good first issue category?
19:00:04 <bcotton> including, i think
19:00:08 <py0xc3[m]> I can then prepare the dashboard
19:00:09 <pboy> I think including!
19:00:09 <darknao> osezer[m]: there is coffee and cookies in the back
19:00:17 <py0xc3[m]> bcotton: Ok. +1
19:00:30 <bcotton> #agreed We'll start using the workflow proposed by py0xc3
19:00:35 <bcotton> #action py0xc3 to prepare the GitLab dashboard for the workflow
19:00:38 <py0xc3[m]> I will prepare the dashboard and the labels until the next meeting
19:00:49 <bcotton> #action py0xc3 to add the workflow docs to the team docs
19:02:17 <bcotton> anything else on this before we move on?
19:02:38 <darknao> not from me
19:03:33 <bcotton> #topic Discussing how to intergrate the HowTo
19:03:33 <bcotton> #link https://discussion.fedoraproject.org/t/preparing-the-docs-meeting-discussing-how-to-integrate-the-howto/40822
19:03:44 <py0xc3[m]> darknao: You are right: it seems that I can add the externals if he/she wrote a comment within an issue or an open or merged MR. Only in MR that are already closed I cannot assign externals for some reason, but that ain't important anyway.
19:03:45 <bcotton> speaking of py0xc3's ideas :-)
19:04:01 <py0xc3[m]> Even more of me :O
19:05:07 <darknao> I vote +1 to convert the how-to in adoc format
19:05:16 <py0xc3[m]> A major question I didn't consider yet might be if this could be even done without much efforts. I don't know the framework we are using
19:06:35 <pboy> darknao +1
19:06:46 <py0xc3[m]> darknao: I'm fine with that. I can prepare a draft within the next weeks.
19:06:58 <darknao> the thing that bothers me most is it's highly focussed on gitlab, and gitlab is just a small piece of the docs components
19:07:04 <darknao> what about pagure or github?
19:07:29 <darknao> if we add that to the toolbar, it needs to be relevant for all the docs, not just a portion of it
19:08:08 <py0xc3[m]> Well, do we have Docs on github? In terms of pagure, I assumed we will shift to GitLab on the long term anyway. The goal was to keep the process as simple and short as possible.
19:08:27 * osezer[m] was curious about is all docs going to live in gitlab or pagure ? (atm it is both and sort of confusing as well)
19:08:27 <py0xc3[m]> darknao: you are right. It doesnt make sense as long as there are still repos at pagure
19:08:29 <bcotton> Fedora IoT has their docs on GitHub
19:08:36 <darknao> some stats: there is 41 pagure repo, 11 gitlab, and 6 github
19:08:59 <bcotton> Onuralp Sezer: docs that the Docs team owns are going to be in GitLab. Other teams can put theirs wherever
19:09:13 <py0xc3[m]> Ah, ok. Didnt know about GitHub.
19:09:26 <py0xc3[m]> As far as I read it, other teams of pagure, DEI etc, also planned to move
19:09:34 <pboy> I'm not amused about github
19:09:42 <bcotton> but most of the user-facing docs are going to live in GitLab, so I think it's okay to focus on that
19:09:51 <osezer[m]> Ben Cotton (he/him):  Wouldn't be nice to have them all in one place ?  ( I don't wanna force them but still one place is better and easier to control find / manage etc)
19:10:24 <py0xc3[m]> I can add a comment about GItHub to the HowTo. Does that make sense? I didnt know about that.
19:10:24 <osezer[m]> darknao:  thank you for stats
19:10:31 <bcotton> Onuralp Sezer: no. or at least it depends on how you define "one place". imo, it's better for a team that maintains its own docs to have the docs live where the rest of their work lives
19:10:50 <osezer[m]> okay fair
19:11:20 <pboy> We are far too tattered as Fedora.
19:12:02 <pboy> Usally everything should live on fedora repos
19:12:29 <pboy> But that's not a topic of today. :-)
19:13:00 <bcotton> py0xc3: yeah, i think that makes sense. we can just say something like "these instructions apply to documentation sources hosted on GitLab. For other git hosting sites, see the site's documentation" or soemthing like that
19:13:14 <bcotton> github has pretty good docs, so we can link there. pagure...well....not so much
19:13:40 <py0xc3[m]> I will add something for GitHub, and for now maybe also pagure, as there is still much on pagure. Hopefully this will change soon
19:15:55 <bcotton> works for me!
19:16:06 <darknao> +1
19:16:40 <bcotton> #action py0xc3 to add the "7-step howto" (focused on GitLab, but with links to GitHub and Pagure docs) to the contributing docs
19:16:42 <py0xc3[m]> plus make a adoc draft. But I am not sure if I can do that before the next meeting.
19:16:53 <bcotton> anything else we can make py0xc3 do? ;-)
19:17:02 <py0xc3[m]> :D
19:17:15 <osezer[m]> translate all docs :P
19:17:31 <py0xc3[m]> Onuralp Sezer: consider it done 😎
19:17:51 <osezer[m]> py0xc3++
19:20:22 <darknao> so, how about the location of the link now?
19:20:34 <bcotton> what link?
19:20:41 <darknao> the how-to link
19:20:45 <bcotton> ah yes
19:21:04 <bcotton> i'm in favor of putting it in the footer, for reasons I articulated in the thread
19:21:16 <darknao> I would rather see it replace the "want to help" banner in the footer
19:21:17 <bcotton> anyone else have opinions?
19:21:23 <pboy> I would prefer a graphical element
19:21:41 <pboy> beyond the toc, e.g.
19:21:59 <pboy> the footer is a bit "hidden"
19:22:29 <pboy> it should be highly visible
19:23:00 <hankuoffroad[m]> pboy: yes
19:23:09 <py0xc3[m]> pboy: That was my concern too
19:23:22 <darknao> the "want to help" banner seems quite visible to me, and I think the current link there is not really helpful for new contributors
19:24:05 <pboy> (looking for the want to help banner)
19:24:10 <py0xc3[m]> darknao: The issue is, it is visible only if someone ends up at the end of the page.
19:24:12 <darknao> somewhere around the toc might be complicated to implement, as it's not always there
19:24:42 <osezer[m]> maybe put it on right upper corner  ? (next to search but stays left side of search so search is still stays on corner)
19:24:57 <darknao> well, in that case, if you want something really visible, the toolbar seems not so bad
19:25:04 <osezer[m]> also put one in main page with "blue" box maybe as well
19:25:43 <py0xc3[m]> So like https://aws1.discourse-cdn.com/business4/uploads/fedoraproject/original/2X/2/2ed3de7e0b2a6c080a2269120e2b247a1f4a8371.png but one above, next to the search button?
19:26:00 <darknao> I mean, I might even be able to make it visible only if you're on a gitlab doc component
19:26:05 <pboy> why not beyond the "content" list?
19:26:12 <darknao> (related to the last topic)
19:26:25 <pboy> a fat red flag with the text and link?
19:26:53 <osezer[m]> py0xc3:  yes
19:27:40 <py0xc3[m]> Would make sense to me, if it can be implemented easily.
19:28:05 <darknao> py0xc3[m]: the "navbar"  is quite empty right now, so yes, that can be done
19:29:11 <darknao> everyone is on board with the button text? "7-click Edit HowTo"?
19:29:30 <py0xc3[m]> I would say it doesnt make a big difference if it is next to the search or next to the history/edit/issue buttons, so I would use whatever is easier to implement/maintain
19:29:44 * osezer[m] uploaded an image: (9KiB) < https://libera.ems.host/_matrix/media/r0/download/fedora.im/1f0a0ffebc5bcf29b86cd3ed56d096ad0e167803/image.png >
19:30:44 <py0xc3[m]> darknao: Well, that was just a first shot for discussion :) the idea was that it indicates "make an edit, which is easy and quick"
19:30:54 <darknao> I think it make more sense to go on the navbar
19:30:59 <darknao> so +1 for that
19:31:02 <pboy> I'm still think in terms of a campain: How easy it is to contribute, try yourselv, 7 seps .....
19:31:21 <darknao> the text should not be too long either
19:31:30 <pboy> on the right margin, in the middle
19:33:00 <pboy> we should use that 7-steps howto for an onboarding campaign.
19:34:05 <darknao> we are overtime, we should continue this conversation next time
19:34:24 <bcotton> yeah, let's finish this up in a Discussion thread
19:34:27 <pboy> agree
19:34:32 <bcotton> or just do something and decide later if we want to change it :-)
19:34:38 <bcotton> thanks everyone!
19:34:49 <py0xc3[m]> Agree
19:34:54 <py0xc3[m]> Thanks!
19:34:59 <bcotton> #endmeeting