Docs meeting agenda: 2023-05-06

Here’s the agenda for the meeting 2023-05-03T18:30:00Z in #fedora-meeting-1:

  • Announcements
  • Tickets review: No tickets marked for the meeting (feel free to mark tickets and post them here)
  • Quick docs update [1]
  • Possible Docs team work plan for the F39 / F40 period
  • Consequences of darknao’s decision, and ensuring future consistency in coordinating meetings (agenda), prioritizing tasks and new roles required in Docs team
  • Verify consensus for @pboy 's suggestion about GitLab guide [2]
    • If agreed: How to conduct with the “unmaintained”? [3]
  • Your topics here!
  • Open floor

[1] Feel free to correct me, but I guess this is a “weekly topic” at the moment (?)

[2] I think there is already a consensus towards @pboy 's approach to (interim) stop maintaining the GitLab guide until we know where the GitLab UI is developing to (if it will become “maintainable” again in terms of the speed of changes we have to adjust the guide to, and if the outcome of the current GitLab UI developments can serve any non-gitlab-specialized audience that needs a guide beyond the GitLab Docs).

[3] If we agree on [2], the question is if we want to keep the guide on the page visible to all visitors: it might be confusing and/or annoying and thus deterring for users if we put something obsolete in their “first line” of visibility (creating bad impressions of our conduct, or make them think they are dumb when they do not get it done). Potential solutions (feel free to add further):

  • Remove the button temporarily (I can check, but do not know if we can do that easily)
  • Change the page to have a CAUTION box that tells the users what is going on with this guide
    • Add a box to the top of the page and leave the remaining content online or
    • Add a box to the top of the page and delete temporarily the remaining content, which can be easily restored for updates later
    • Add a box to the top of the page and replace content by links to easy-to-use tools like hackmd, etherpad, … that can be used to forward information to us
  • Leave it as is it
  • Other alternatives?

Shall I add Possible Docs team work plan for the F39 / F40 period to the agenda as well?

Docs team needs a person to chair the meeting today. Could you @py0xc3 or @pboy do that?

We also need to consider a short to medium term consistency in coordinating meetings (agenda) and prioritizing tasks and new roles required in Docs team, and how to recruit them.

We have a few topics @pboy put forward to run through.

Yeah, you are right. We have to make sure that someone starts the meeting. I can do that.

Specifically, we should discuss our working plan and about the consequences of darknao’s decision.

1 Like

Yes, i think we should continue the discussion.

Indeed! I added these points to the agenda. I think they are more time critical than the GitLab stuff, so I put them before GitLab.

Thanks :slight_smile: I am not sure if I would have time to get into controlling the bot until tomorrow :dizzy_face:

@py0xc3 about easiest options to contribute without complications, I’m inspired by ideas here;

Indeed, adding the possibility for users to use easy stuff like Etherpad is a good idea instead of the “high entry barrier” to opening tickets or logging into Matrix. At least in collecting issues around content it might be helpful to improve our overview, maybe more!

This would lead to another possibility: Replace the GitLab HowTo content by links to Etherpad and such, and a simple box or something like that that shortly elaborates about it?

Hmm… We have to be careful that adding the contribution does not create comparable or more work than introducing the contribution. We have to be able to manage what we get. With Libreoffice, we have already formatting that can cause trouble. I would stick with online tools, to ensure the product is something we can introduce and that it has some common format (avoiding files and such).

We need to consider side effects put on editors or reviewers if we open up various routes to contribute. I can support open issue ticket options (and interact with contributors using issue comments) as it now, but not so keen to email/Discussion. I have already too many toolsets.

I’m not endorsing any of tools listed. It was just an example posted in Docs related thread in the Fedora Magazine.

But would it not increase the problem if you had to also manage processing different files and file formats and invest time to convert them to the needs of Docs? With Libreoffice I am worrying that people send files that use odt bold and such, with people not knowing about the need to use asciiDoc by writing instead of clicking LibreOffice’s “bold” button (just an example).

I understood you the way that we might consider any such tool as “easy-to-use” and “immediately-to-use” tool that can enable any user without long ways through logins and MR to quickly and easily contribute. So that everyone can leave us information, may it be “hey page abc is obsolete” or already a suggestion about “REMOVE abc & ADD def”, right? So focusing on the concept, not yet any specific tool at this point.

Discourse will send me a friendly reminder to consolidate my responses, so I will summarize my thoughts and we can discuss more in Chat later or meeting if time permits.

  • three alternative options are something we can consider (not as solution)
  • we need to think about reviewers perspectives before making decisions
  • ask other members for options and wait

Personally, I don’t want to add other options.

Generally, the options are not intended as long term solutions, just to have something interim that is at least not “destructive” (confusing, making feel incompetent, deterring) until we can implement exactly what you propose and how you propose. We are 100% same page about this need :slight_smile: I think I understand your point now, see you later in the chat :wink:

  • Tickets review: No tickets marked for the meeting (feel free to mark tickets and post them here)
  • Quick docs update

At the moment, issue/PR labelled as meeting in GitLab docs repo is discussed in weekly meeting.

Every issue/PR comment is valuable. If issue/PR is unattended for months, a casual contributor is quite unlikely to come back for another contributions. There is no excuse for existing members whatever resource limitation we have.

I allocate one hour every week to go through issue tickets/PR in QuickDocs and GitLab Docs repo.

How about including minor and major issues on Docs repos (QuickDocs and Docs pages/UI)? One of the major reasons/motivations that made me stay in Docs team is prompt and clear feedback through issue/PR comments from a number of reviewers. I learn from it every time and feel rewarded.

According to the workflow, an unassigned/unprocessed issue ticket has to be put to the meeting once it has reached a certain age to evaluate how to proceed. So this used to be considered. I have not yet done a review since I have returned. But that’s one of the issues I meant when I opened a topic about the workflow and the GitLab dashboard, which does no longer implement it → Triage category in GitLab workflow: necessary or confusing? → at the moment the dashboard does not really create a clear overview, so that the rule you are referring to (review old tickets) can only be implemented if someone goes through each ticket each week to check which unassigned/unprocessed ticket is “practically unassigned/unprocessed” (and vice versa) and additionally has reached the age for re-evaluation. I currently prefer to not open/comment specific problems like this one since I am not yet used to how things are handled at the moment and how far things I see are intended or not. So I kept it generic with the topic.

But my assumption is that what you are referring to might be too much for this one meeting, isn’t it? Maybe that should be a discourse topic first to consolidate/discuss incentives and ideas, as I could imagine it would otherwise occupy more than one hour in meetings. What do you think?

Originally, the workflow was intended to avoid this (so, keep such things informal and tackle it here or in GitLab asynchronously). The problem is: this one point can occupy the whole meeting, if not more. I remember back then, meetings had to be often interrupted because 1 hour was no longer sufficient, and each week more was accumulated than processed.

However, I already had the perception that tickets seem to be not monitored, especially inside. So I agree that it does not work the originally intended way, and we have to find alternative solutions if you say that the current approach does not tackle these issues (I tried in the noted topic to slowly get in touch with how the currently informal flows are working).

In most cases, issue/PR review is done asynchronously outside the meeting.
I mean increasing the types of labels for meeting, so we “leave no stone unturned”.

Issue/PR review doesn’t have to be every week or every minor/major label. We could skip pending ticket review on certain week, but it has to be regular (at least 1 a month during meeting).

We could look at ways to measure our contributions (even without massive analytics efforts);

  • Number of issues opened/closed in this month
  • Number of PRs closed in this month
  • Number of pending issue/PRs
  • What could be posted to ‘EasyFix’ page?

As I said, I don’t know what is informally practiced or expected atm, so my arguments have to be taken with care, but as far as it concerns the formal workflow, if you see a ticket that you think is worth to be considered, you can always label it. I think at some page we even wrote that even if someone is unsure, just label it, since we preferred to have too many labelled tickets for the meeting than leaving one relevant unconsidered.

Side effect of limiting ‘meeting’ label only for weekly meeting is that I abused the meeting label often. Okay, for me who stayed less than a year in Docs team, I used label incorrectly by mistake. It is nothing to do with any preference on informal or formal.