Docs meeting process ideas

As Peter alluded to in Fedora and CentOS Docs Revitalization - #6 by pboy, we need to figure out how meetings will work generally. We want to make it easy for people to know what’s on the agenda for the upcoming meeting and what has been discussed in previous meetings.

The Server Working Group posts links to a table on their wiki page. I’m not particularly fond of that approach, although I can see reasons for adopting it. My initial reaction was to say “let’s point people at Meetbot”, but that only addresses the second half of the goal. It does not share an agenda ahead of time.

So maybe what we can do is at the end of each meeting, start a Discussion topic for the next meeting where we can collaboratively discuss the upcoming agenda. The links to the minutes from that meeting would then go at the end of the thread. This, combined with Meetbot’s search, is probably sufficient for our needs.

Another approach to agenda building is to open issues that get tagged with the “meeting” label. However, we have so many repos that consolidating these would be a challenge (unless we added yet another repo that was just for meta work). So I think this approach is off the table for the time being.

I certainly have my opinions about how I would do it if I were making the decision in a vaccuum, but I am explicitly not wanting to dictate how this works because I want to be able to step back once the team is self-sustaining. So what does everyone else think?

1 Like

Could a tag here (or “[meeting]” in the topic name?) not be used to mark topics that need to be discussed in a meeting? That way a new housekeeping pagure project won’t be required just for this, and nor will a special topic to discuss what needs discussing at a meeting. Discussions just start here, and if they need to be discussed in a meeting, they get “promoted”?

I guess the meeting tag could be used by all teams here if they wish. So a topic for a docs meeting gets #docs and #meeting?

Some cursory remarks:

We post not just links, but most importantly a (short) list of topics covered. The links then allow you to quickly access details.

This gives a quick insight into context and process. It is a completely different approach than searching in meetbot or placing links in individual threads scattered around. It’s a long term and systematic approach to continuity and reliability (not to adorn myself with false feathers: this is not my initiative, that’s what server WG has done from the very beginning).

Full agreement. This should perhaps also include a summary of what has been achieved.

Server and Workstation WG follow this strategy. The issues provide a problem-centered perspective orthogonal to the progression perspective of the discussion/threads. Both WGs also use the pagure boards to provide an overall view (Server, Workstation).

We already have a repo where we started: fedora-docs / docs-fp-o. Why shouldn’t we just take advantage of that?

Why not make suggestions based on your experience?

We certainly can. The reason I’m hesitant about it is that if an issue in another repo needs to be tagged for a meeting, we can’t easily combine them. So we’d have to create an issue in docs-fp-o as a placeholder. That will work, of course, but it’s a little more overhead. Most groups that use a “tag the issue” model have one, maybe two repos that they’re working from. We have many.

I’m not opposed to it, and if everyone thinks the overhead is worthwhile, then let’s do it.

I did. That’s what this thread is.

We could use a meeting tag. Matthew is on vacation, so he can’t speak for himself, but I think that’s not the intent for tags in the current configuration of Discourse. Definitely for a category-centric model, that would work. I’m less sure about doing it here.

Using [meeting] in the subject would work. We just need to make sure we have enough people who can edit the subject of posts in order to tag it.

My arguments have to be taken with care as I am not yet very deep into the topic. But especially if the repos move to GitLab, a meta repo should be considered. The dashboard with issues would seem to be an appropriate way to organize and unify such loosely interconnected workflows. Summaries of the meetings in discourse are rigid and its contents not distinct, not able to manage asynchronous processes & tasks. To achieve self-sustainability, organization has to come together at some point, and allocation and creation of tasks has to be comprehensible, documented, and a real time overview has to be available (the categorization is a big issue in using discourse).

The date of the meeting does not tell me the where/who/what/when of the tasks (and which tasks are currently open or to be started, and in which thread are they primarily organized? How to know if there is another thread about it?), and maybe a task may be part of many meetings. Dedicated threads will also not solve the problem, especially without tags. How to find out what is going on in general without the risk of missing a thread, or accidentally not reading a relevant sentence in the recent posts? Or again, if there is another thread that splits organization? This is to informal in my opinion to achieve persistent self-sustainability and a unified Docs that does not split.

A meta repo with dashboard can be used to unify and keep unified; meetings can use it to identify what has to be discussed/allocated/created (a common overview everyone can have open on the desktop; real time shifting tasks among the pipeline categories & do allocation). Also, in between meetings, people can put forward new ideas of what has to be done (e.g. a change in a Doc or so), putting it into the first dashboard category “to be discussed”. Then, it can be discussed precisely in its issue ticket, well documented for the future and e.g. as precedent (not bound to the next meeting). And then it may be closed or pushed to the next category “to be done”. Maybe also helpful if someone finds something that has to be done but is not able to do it immediately himself/herself. People can see what is open and pull tasks if they can spare time, because of the easy overview. Just some examples. I made good experiences with organizing such work around that.

Categories in the dashboard for issues could be things like “to be discussed”, “to be allocated”, “minor to be allocated”, “minor in process”, “major in process”, closed . Of course this is what you should discuss as I am not yet qualified to determine appropriate categories :slight_smile:

Just some thoughts from previous projects, although my previous experience is just partly comparable.

1 Like

Just that you know what I mean (if you have not used it before):

→ It can have multiple dashboards (although issues are in common; labels help to exclude/include them in specific boards).
→ Issues can be marked with one or multiple labels.
→ It can be subscribed to labels! (e.g., QuickDocs, or major changes, or such; I have not used this function before)
→ Labels can be used to create the different categories. Issues can be shifted among the lists/categories with the mouse.

The more we talk about it, the more I’m on board with the idea of a meta repo. In particular, I had totally forgotten about the GitLab dashboard feature. I’ve used something similar on GitHub with reasonable success. So there seems to be some consensus building toward that. Let’s wait a little longer to see what others say.

If we do go that way, I think a Discussion thread is the best short-term solution. I’m not sure if there are any blockers on moving to GitLab at this point. @ryanlerch? If we’re set on moving that way, we don’t have to move all at once, but the shorter the transition period, the less confusing it would be for everyone.

1 Like

So I’ve drafted some documentation based on this thread: Docs team meetings

It’s not linked from anywhere yet since it’s in draft form, but I figure this gives us something more concrete to work against. Improvements welcome!

1 Like

A good approach to get started.

We should definitely create a ticket for each activity (#action) that is expected to last longer than a few days or until the next meeting. And a reference to this ticket should be part of the #action text (I hope this is technically possible).

Great point! We can either include the ticket number or URL in the action, or use the #link command immediately after so that it’s clear in the minutes. I don’t think one is particularly better than the other, so long as it’s obvious to the reader what issue we’re referring to.

I hope I’m not being too terribly pragmatic and results-oriented.

Right now we obviously have 0 (zero) evidence of ongoing documentation activity to track (there may be 1-2 activities as a result of Matthew calling a few weeks ago). As limited as pagure may be, it can manage with 0 activities. And if our revitalization effort turns out to be very successful, we’ll be lucky if in 2-3 months we have maybe 10 documentation activities to track and enter into a meta-repository. Even with that, pagure should not be overwhelmed. And right now we have 0 people willing to do the work and take responsibility for it. Now, before we invest time and effort to develop something new that 0 people could possibly use for 0 activities to track, we should find n>0 people willing to do the work and take responsibility for n>0 really ongoing activities. And we should then ask these people what tools they want or need to use, and offer and ensure to exactly build these tools.

This may be Gitlab in a specific configuration of the dashboard. Or maybe it’s something else entirely. And it is also quite right to collect ideas for possible tools right now, so that those who are hopefully willing to do the appropriate work can build on such support. But we must not do the 2nd step before the first. Otherwise, we might just make the situation worse.

Example of such a mishap is #server here on discussion. Unfortunately, the people who manage servers, ensure their functioning and know every bit and byte were missed to be involved in advance. As a result, none of them participate and so the knowledge needed to answer questions adequately is not available. Users get inaccurate or inadequate solutions and prefer to leave Fedora and find a distribution that solves it better. Members of the server WG are mostly “hard core” system administrators, a special brew for whom even a mouse is a suspiciously inefficient tool. They are unlikely to be willing to give up the existing communication tool, optimized for keyboard and 10-finger operation, for discussion board, or to take on the extra work of participating in both.
In the end, the wrong order here is quite a disaster for Fedora.

Not sure I understood this correctly. Do you mean people working and contributing to Fedora Docs? It may help to narrow down what you mean if so. My email inbox is constantly exploding with evidence of the contrary. In fact, the huge amount of noise I get for all Fedora Docs repos all the time is one thing that makes it difficult for me to keep up and follow the more serious discussions around Fedora Docs (although Discourse is helping a lot for that!).

One idea we could consider is trying to make explicit invitations to the various committers working and participating across all Fedora Docs repositories. There are people doing this work, although I suspect they fall outside the general category of what we might consider as “docs contributors.” This is similar to what I alluded to in this post about distinguishing Fedora Docs leadership and Fedora Docs content writing. But we may have people in the content writing group who may have a greater chance of wanting to contribute to the leadership group. And some people won’t want that either. That’s fine too!

That said, making some explicit invitations and inviting them into this conversations could be helpful, since many of them are opt-in (i.e. I am subscribed to hundreds of Fedora Docs Pagure repos as a member of the Pagure committer group and I also manually subscribed to posts in the #docs tag).

1 Like

Yes, contributing to the “central” Fedora user docs, i.e. Installation Guide, Administrator’s Guide and Quick Docs. The Fedora Editions, engineering teams and other groups write their own docs and have their own ways to track progress. We as docs group don’t need to track those.

Is it really about content?

A good idea and worth to try.