Docs meeting agenda: 2023-05-06

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.

I think there is no “by mistake”. Always mark a ticket for the meeting if you are unsure. If there is not much to discuss about a ticket, it will be solved in a few seconds anyway, so it will not cause harm. This is better than have a relevant ticket unconsidered. Also, if it is marked for the meeting, it may be already facilitate some “immediate discussion” in discourse in the “Docs meeting agenda: XXXX-XX-XX” thread, as we do it at the moment here. @pboy maybe has a better feeling with what makes most sense atm, but I would stick with “mark everything you could imagine to be relevant for the meeting”. A common “informal average” will develop over time about what tends to be marked.

It is not explicitly mentioned, but you can always open a topic about tickets, to raise some attention and/or facilitate discussions. I like that idea, indeed: if anyone perceives that the number of “meeting” tickets could bypass the capabilities of one meeting or if some need more detailed/time-critical consideration, just open a topic → this cannot create harm but only contribute to solving issues.

Detailed meeting information:

Essentials

  • Next meeting we want to create a prioritized list of open design changes
  • With all the difficulties, we want to continue to constantly update our GitLab Contributor documentation to reflect the ongoing changes.

As an after-thought, what tripped me over about updating a guide or not could be the word “unmaintained”. I guess the term has ubiquitous meaning among package developers and maintainers - if a package is not maintained, it will be flagged as orphaned and removed from the next release. Does it not?

What I could offer to my best intention is;

  • Get feedback from users
  • Assess possible simplification in process or wording with feedback received
  • Check consistency across contributor guide
  • Discuss ideas for updating the guides

Being unmaintained leads to the package being orphaned, because it no
longer has a maintainer, which means it no longer receives updates (but
it still can get new builds). No updates can lead at some point to
security and stability issues (or that builds no longer work for some
reasons). However, in some circumstances, a package might be kept even
if it is not maintained.

So I used the term in the correct meaning: a GitLab guide to receive no
longer updates or adjustments to changing circumstances, which can break
its content once further changes are applied by GitLab, or cause other
issues that need maintenance.

But we found already out that we had a misunderstanding about what we
interpreted from the “waiting” for further GitLab changes before going
ahead (the comment we were talking about yesterday). I interpreted the
guide being unmaintained from that point on until there is a decision if
we can and want to maintain it again, or if we cannot and thus get rid
of it at all.

So I meant WHAT the term “unmaintained” implies, but THAT it applies was
a misunderstanding :smiley:

1 Like

Could you recap what open design changes are for the Docs page? Who are the best representatives to assess the current situation and prioritize? Design is not my forte.

We have some tickets about design issues. I remember the invisible burger menu on smartphone screen, we wanted to have an abstract paragraph, or we wanted to graphically emphasize the issue and the edit button in the top bar. But there are some more.

You are right, it’s Monday, we should start to compose a list otherwise we can’t discuss it on Wednesday.

I love a challenge beyond my comfort zone. But in this occasion I won’t be able to contribute to Docs design work. I think we need more alignment and discussions with relevant teams prior to weekly meeting. With that in mind, we could avoid screaming into the void.

i got an impression that a previous thread titled Docs design work is rather evolved around aesthetics over form.

I was hoping for design principles associated with user experience, usability, and a11y.

At the moment, as a first step, I think we have to focus on what we have, the current design of the home page. I’m not aware of any planning to rework the current design, nor do I see any resources. But that may change in the near future, because the Fedora Website revamp project may continue with the next step.

And before we discuss design, I think we should collect a list of known design issues and make a plan how to make progress.

Urgent usability issues like the dark-mode styling are already in progress. I recall thin scrolling bar, too. I just need to limit my time to what I can do best rather than piling up a list of issues during meeting.