How do we make decisions?

Okay, as I #action-ed myself in last week’s meeting, here’s my thoughts on how we’ll make decisions as a team.

The short version: For process and meta work, we operate on the basis of general consensus. Proposals should be made on Discussion and allow several days to a week for input from the rest of the team.

For content/tooling changes, significant changes should be made via pull request to allow comment. Pull requests shouldn’t be made for at least one day, and should wait until there’s a general consensus. Trivial changes can be made directly at the discretion of the person making the change.

The longer thoughts: Some teams have specific voting policies. This necessarily requires a well-defined membership requirement. For our purposes, this seems to present an unnecessary obstacle to participation. In general, we want people who are infrequent contributors to feel welcome participating in Docs. However, that means we can’t require unanimity or even majority (how do you determine the minority of a loosely-defined set?). If we come to a general consensus as a group, then that’s enough to move forward.

The reasoning behind the Discussion thread and PR requirements is to allow participation by people who can’t actively watch all day. It also ensures that contributors from any time zone have the opportunity to weigh in. In general, we need to require asynchronous decision-making in order to be more inclusive. For our purposes, we should almost never make significant decisions in a meeting.

I don’t address how we grant repo access to new contributors here. That’s the subject of another thread (I’d welcome someone else to kick that off).

What do y’all think?


At first some casual remarks

  1. Decision is inevitably directly linked to responsibility and commitment to actually implement a decision.

  2. And responsibility and commitment is inevitably directly linked to the authorization to make changes to the repository.

  3. And thus the circle of those who are authorized to make changes are the ones who ultimately and effectively make the decision.

  4. And the circle of those who are currently authorized to make changes is, on the one hand, the group of people who is responsible for the current (somewhat miserable) state of documentation and, at the same time, the only one who could ultimately change and improve it.

I think your considerations fall a little short. The participation of occasional contributors is indeed very important and will be the “icing on the cake” in the future. But we also need to think about how to initiate consistent and continuous evolution and involvement over the long term. So we particularly need “proven contributors” who contribute reliably in the long term.

In the long term, we need a kind of “FESCO for documentation”. And in the short term, we need a migration path to it. So how we make decisions can only be determined transitionally at the moment.

I think we should take 4 steps now:

  1. We need a list of those who have administrative permission to our repos and a statement in each case as to whether they are still willing and able to do appropriate work and participate in the process by contributing hours of work.

  2. We need to decide on a list of the 3 or 4 most essential content items (and possibly tooling needed for this) that we want to achieve in the next about 3 months. We should make this decision at 2-3 consecutive meetings, supported by a discussion thread. That way, everyone who is really interested should get a suitable opportunity to participate.
    This, of course, includes finding people from our community who are willing to commit the appropriate hours of work.

  3. We then need to determine a tool that we can use to track progress and really start immediately.

  4. We can then use these 3 months or so to find a responsible team that is provably capable of bringing about a positive development. And this team then ultimately makes the decisions, of course, on the basis of a broad and consensual agreement. So we get a kind of “proven contributors”.

1 Like

Since I’m not very deep into Docs yet, I’ll hold back on comments. But a few remarks:

I am not 100% sure if I got your point (FESCO in terms of being on par in the organization level, or in terms of the number of people? Or just having a more formally organized structure?). If it is the first, is this really necessary (in terms of fostering the goals of Docs) and does it really solve/reduce the issues we have now? If it’s the second, I think this is not realistic to achieve, is it?

If it is the third, I would agree that creating more formal (and documented) structures could help in many respects. The entry barrier to the team is very high as everyone has to come to the team actively and ask what they would be up against if the join, they don’t know in advance what this is about. However, if they connect to get that information, it feels bad to then say “sorry, that’s too much for me” or “sorry, I’m not qualified for that”. People don’t want to be in such a situation. This is a psychological thing that maybe should be avoided if possible, and maybe one of the reasons for the personnel issue.

The git introduction of Ben and the draft for the meetings are already a good start. I would also add the Group fedora-docs - page to the git intro (it offered me the overview I was seeking), so that people have an overview of what Docs includes/is about (and maybe what else is included). Also, an introduction to the workflow and “how to do what” (including responsibilities, decision-making, and so on) makes sense (as soon as it is determined). This implies just an abstract overview, no dedicated Doc or such :wink:

That was my goal with the GitLab dashboard :slight_smile: Although the dashboard is intended for managing the “day to day” work of Docs (in short, managing the work related to the content and its development; this includes discussing pull requests which are related to the content (the issue ticket) and not to the date as the meeting), but not to manage Docs as “Fedora entity” itself (organizational architecture issues, long term issues/development, necessary adjustments, strategic issues). The latter needs a different structure (Discourse & the meetings are appropriate for this) with different “primary keys” to discuss, sort and find (or simply, organize) things that are not reappearing in the same manner and not standardized like content management :slight_smile: So my approach does not exclude Ben’s argument:

In short, I wanted to say that GitLab dash is for managing the product of Docs (the processes), Discourse/meetings to manage Docs (the projects) :slight_smile:

Are we talking here primarily about employee retention? Indeed something that is worth to be discussed in terms of how to achieve that, if there is an issue with keeping contributors on the longer term (is this the case?).

Concerning the issue of employee retention (if this is an issue), I disagree a bit with that. Clear affiliation is a thing that gives the people something back. A type of recognition for their work. If I understand you correctly, your point would make it not worth much to be a contributor here. However, this is a very shaky point. What do you think? Maybe it is worth to think how to independently from each other facilitate infrequent contributors but also the “proven contributors/responsible team” PBoy was talking about? I don’t know how much difference this makes in managing content. But keeping the team self-sustaining would indeed make it necessary to have a reliable “core” team.

That’s true. But I also wouldn’t want to necessarily limit voting to the core team, unless we draw it broadly, which again is somewhat logistically challenging. To @pboy’s point about having a “FESCo for docs”, I disagree with that, in part because I don’t see it being viable. In the ~13 years I’ve been involved in Fedora, the Docs team has never had that level of formality. It’s always been based on consensus and mutual accountability without explicit authority. On the other hand, perhaps having a more structured approach would make it more self-sustainable. So I’m not opposed to trying it out.

I’m not sure we need to get on that path quite yet. I agree with the general principle that it helps to know what you’re working toward, and I agree with the fact that we can only make transitional processes at the moment. Which is my goal with this thread. I’m not trying to (nor do I want to) decide how the team will function in perpetuity for now. I just want us to have enough of a framework to get started.

Once the team is spun up and community-led, my goal is to step back so I’m not overcommitted. If the general consensus is that we should have a formal structure goal and immediately start working toward that, I will defer to the consensus. I just don’t want to see us getting too wrapped up in defining a process that has historically not existed for this team and end up losing the forward progress we make in the coming months.

I think this is a good idea regardless of what sort of team structure we’re working toward. If nothing else, removing people who are no longer interested in participating spares them some email from the repos. :slight_smile:

I just started another thread about using docs-fp-o to be our meta work tracker. If we all seem to be okay with that as a short-term solution, I’ll open a ticket for the repo membership cleanup early next week.

With “core” I just meant those who are persistently active and on whom it can be relied on in terms of responsibility/continuing contribution (to separate them from the infrequent contributors) . It is not intended to be limited by a specific, pre-determined number or such (I focused on the core as something that takes over responsibility for critical organization/tasks/processes, not on something that is eligible to vote; I didn’t consider voting yet it my argument). But maybe something like the IETF’s NomCom could be a model? If someone participated (actively?) in the recent (just an example) 10 meetings, it can be assumed that he/she knows about current issues and is eligible to vote (this is unbiased). Maybe additionally a minimum number of Discourse posts (read/write?) related to #docs? Something like that maybe? It is not obligatory to bind voting rights to the frequent core. frequent / non-frequent & voting right / no voting right may be two different distinctions, not related to each other. But it remains the question, is there a need for formal votes? And what are the tasks that have to be allocated to the frequent core, to keep things organized and together? Is it just organizing meetings and, if there is no vote, derive the consensus? That’s nothing I can answer yet.

As mentioned, I am not for sure if I got pboy’s argument right. But I meant only more formality than now, not the level of FESCo. I agree that this would create more issues that it would solve. Something in between :slight_smile:

I mean that in terms of commitment and accountability / responsibility. I always like to quote Stephen Smoogen on this when we were discussing membership requirements for the (formally defined) Server WG back in the day: "Being a member of a working group is basically a commitment for N hours a week to do whatever is needed for the group to get an edition out the door. It may be writing tests for QA, it may be writing documentation, it may be sitting in multiple meetings in a week to reach a consensus on what is getting done in this edition, and it may be coming in every morning and finding out why a server compose broke (versus others) and see which commit did it. It is called a ‘working’ group for that reason. " You can translate that accordingly to docs.

Maybe the FESCo structure is a bit too strict. On the other hand, in the end, docs is of the same importance as our packaging and maintaining efforts. All this technical work and what I consider to be excellent results can be brought to broader public use only if there is adequate documentation. Otherwise, we’ll end up as a perhaps interesting, but practically useless / unusable experimental exercise (and we already are a bit).

From my point of view, docs is not a “fancy to have”, not an “icing on the cake”, and not a “social drivel” either, which is rather beside the point for a technically sophisticated distribution and work / activity.

We need to take care of continuity, quality and reliability of documentation with exactly the same care that we take care of continuity, quality and reliability of the technical side (that is structures like FESCo and “Working Groups”). For the technical side, we would never accept a situation like it was true for docs in the last years.

1 Like

I would bet FESCo claims to work “based on consensus and mutual accountability” (and with “authority” as a fallback in case of emergency).

I am a big fan of consensuality, mutual responsibility, equality of all contributors, and the principle of “one person one vote.”

From a sociologist’s perspective, such an (informal) structure works very well in phases of start-up, innovation, new beginnings, and with smaller groups (about 7 participants). It is a time interesting for all participants and a time to earn merits as innovator and pioneer.
It tends to break down when a phase of consolidation and systematic development is reached. It is a time when it is boring, the work is taken “for granted”, and there are hardly any personal merits to be gained. And above all, it becomes very tedious.

I think that theoretically expected development can be found in fact in docs. When it came to a new start with conversion to adoc/Antora, it worked very well. And when it came to making this structure permanent, it got lost and more or less faded into obscurity. It became an obligation out of a factual interest, and was no longer a fascinating and exciting adventure of experimenting with and learning of new things.

So we need to establish a fallback solution. The model of FESCo may be too formal, maybe the Working Group model or a variation thereof would be a better fit. Anyway, Fedora Council should care about it with the same intensity as with FESCo.

I think it is not about importance but requirements. Different doc pages do not depend on each other like software packages. We don’t have the external pressures of (potentially security critical) upstream updates that have immediately to be introduced and that make further changes/adjustments in other areas necessary, and that may result in even more unforeseen needs/unintended behavior. Docs can be security critical in several respects. But we do not have the “time-critical” factor and the interdependencies (which is in combination a major issue). Security updates that also imply (time and security-)critical updates of the docs are unlikely as the first tends to not change the user experience.

However, independent from a FESCo comparison, I think we have already agreed that a higher level formality is worth to be tested/discussed? Maybe we shift our focus from the “if” question to the “what”?

  • How to determine the committed core members? I made already some suggestions above, I would use ask.fedora (translated: processeing over 10 tickets or 10% in the recent 3 months or so) and/or NomCom (e.g. 10 out of last 15 meetings) as possible models, plus a formal self-commitment. Even if this is determined formally, the small Docs team could implement it informally without technical measures (the task number and the team size is likely to remain sufficiently small I think). (I assume the core would be headed by Pbokoc?)
  • What are the tasks that the committed core will have to take over? The tasks that are obligatory for ensuring continuing self-sustaining organization that does not split? My thoughts would be
    → managing the GitLab dash (if it will be introduced)
    → managing discourse debates
    → managing meetings
    → pushing contributors to use the tools (such as the dash) to ensure the organization to not split and to keep it documented
    → identify urgent needs for changes (due to changes/adjustments/developments in Fedora)
    → moderate, and deriving the consensus in discussions

Btw, I don’t see the need for formal votes (although my experience here is limited obviously). But maybe it could safe a lot of time to use the Discourse voting function within threads to clearly identify which directions/decisions could result in a consensus. The meetings/discussions themselves are often not very distinct and it is strongly probabilistic which argument implies support for which decision (a lot of talk and it is still not distinct what is the common opinion). This can safe a lot of discussions by starting with a rough vote for directions and finally another one to find a consensus (what’s your favorite, what would be ok for you, where do you see further need for discussion).

As far as I know, Matrix has also a voting function which could be used in meetings, doesn’t it?

A lazy approval seems to be fine in these realms. If any infrequent contributor at some point blocks a consensus without constructive reasons, the core could still overrule if the remaining contributors have a consensus (I assume this will not happen).

I opened docs-fp-o 189 that’s open for someone who wants to take it.

An important factor is that Fedora Docs does not have the same investments as other parts of the Fedora Project. Nearly every non-rotating member of the Fedora Council participates as part of their paid job. Nearly every member of FESCo is able to participate as part of their paid job. In my time in Fedora Docs, there was only ever one, maybe two, people who were paid to work on Fedora Docs as part of their primary day job responsibilities.

So, when discussing how to set up decision-making structures for Fedora Docs and how to do so in a sustainable way, we must account for this key difference in how the work behind Fedora Docs is financially supported. This factor distinguishes Fedora Docs from many other parts of the Fedora Project community—it has almost always been driven by volunteer labor, with few exceptions.

I see two areas that could make great entry points on rebooting Fedora Docs:

  1. Distinguishing Fedora Docs leadership from Fedora Docs content writing. Some people may want to participate more in the leadership and technical guidance behind Fedora Docs. Other people may just want to make some improvements and write some content. Historically, we have not done a great job of separating these things. We could do better on distinguishing how people can contribute to Fedora Docs, and giving them access and privileges according to their intent and desire to contribute.
  2. Defining a core, or “proven”, contributor. What distinguishes a casual contributor from someone who has a deeper knowledge of the interworkings of Fedora Docs? Could we narrow down key tasks and responsibilities and put it into a list? I don’t know much about the proven packagers process, but from what I do know, I admire the human-driven way that one proven packager can “sponsor” another into the group. There is some risk of unconscious bias, but I think this can be mitigated with better (wait for it) documentation. :grinning: It still beats the process we have now, where different people will react in inconsistent ways from lack of centralized coordination.

Just some thoughts. I think the committee discussion can be a messy one, and especially noting the volunteer-driven nature of Fedora Docs, it could be difficult to adapt if someone has a sudden change in their day job or personal life that challenges their commitment to Fedora Docs.