Discourse bots & Docs Team meta discussion (process, governance, outreach)

I remembered that the council has a bot that automatically opens tickets here on Discourse for any issues on the Council issue tracker.

Given our discussion around trying to find more reviewers for quick-docs here on Discussion (see this thread), should we see if this bot can be enabled for quick-docs. All tickets/PRs there would then have corresponding topics here?

Here’s the bot:

Here’s an example council ticket posted here by the bot:

Hello @ankursinha ,
After reading the linked thread, I would say this is a good idea. Just putting my 2c worth in here. At least it answers part of the linked threads desired goals. Visibility of quick doc’s review requests.


I think that’s a good idea too. How get we this running? Could you take care of it?

1 Like

Sure. I’ll get in touch with the council folks to see how to get this set up :+1:

@ankursinha Thanks!

Filed Issue #5: Could we have the bot enabled for the quick-docs repo please? - pagure2discourse - Pagure.io

Yes. Sorry for the slow reply. I’ll get to it today!

1 Like

I love our activist contributors. But I wonder where they were when the Docs Team was discussing and planning the further development of Quick Docs. Or is Quick Docs no longer part of the Docs team’s remit and I didn’t notice? That would be fine with me too. Then I could save myself the work with Quick Docs.

Otherwise, it would be important to me to improve Quick Docs in a systematic, planned and coordinated way. Any kind of quick fireworks won’t help. And individual short-term activism doesn’t help with a long-term perspective either, and experience has shown that the good intentions will quickly fizzle out as a result.

And I would be even happier if our activists here would either take full responsibility for Quick Docs - and do so reliably and on a long-term basis - or get involved in the discussion, decision-making and work of the Docs team.

I seem to be missing something — it seemed like you were on board with this, in the posts above. Is there something else I should be aware of before setting this up?

Sorry, maybe I was a bit too short. I think it’s a very good idea, yes. But I would like to incorporate it into the development planning. With a spontaneous introduction, it will quickly fizzle out.

I don’t yet know exactly what the long-term planning will look like. Unfortunately, I’ve been discussing this almost exclusively with myself (and to some extent with Hank) over the last few months. In any case, a revitalization campaign is necessary. We need a resilient structure and grouping and a campaign to launch it - Docs Hackfest, virtual Docs Hackfest, special section of the release party, something like that. And as part of it, this idea could make a systematic and long-term contribution, and we should prepare the setup at this time. All this is a rough idea that still needs to be improved. At the moment, I am still looking for discussion partners and people who could help to refine and improve the plan.

Okay, I will hold off for now. I think a docs hackfest is a great idea in the new year.

I suggested the idea to add team workflow in discussion on top of dev. mailing list. The latter is supported by Ankur.

We need a wide range of contributors (on demand and ad-hoc) to review content and PRs. The work has to be distributed to them rather than being subjected to a grand resilient plan.

If you want to hold this for now pending discussion partners, that’s fine.


@pboy : hullo, I thought you’d agreed this was worth setting up:

Has something changed recently that makes this against the plan?

Cool. I’m afraid I’m out, though. Unfortunately, my volunteering time is quite limited. I can help with concrete tasks to keep things ticking along, but I cannot attend more regular meetings and keep up with more discussion. Since this is the second tweak that has gone against your wishes and plan, I’m going to sit out until the plan is complete and there are smaller tasks for us “activist contributors” to work on. (I’ve removed myself from the quick-docs committers group now)

I’ve been thinking hard about the nature of contributions.

All contributions are welcomed.

You should not have different levels/concepts/eligibility for contributions - short-term or long-term.
We need to embrace all types of contributions with open arms. Arch Wiki is famous for maintaining comprehensive and up-to-date documentations. Linux YouTubers and tech influencers know that. Arch don’t say regular or long-term maintainers. There is no favouritism. More than 400 contributors are working on Arch Wiki. They don’t grade contributions like short-term activists or consistent performers.

@pboy , what you debate here divides community and is against the basic principles of community voluntary work and any pro-bono assignments.

Whatever your intention (or miscommunication) is you need to support with your plan to announce ‘Enable t2dbot for Quick Docs’ and when. You can’t just say ‘let me think about it and hold’.

1 Like

Also, my bot script doesn’t currently handle PRs. I think that’s a good suggestion, but it’d be helpful to know how urgently I should work on that :slight_smile:

@ankursinha, @hankuoffroad : You are pushing the discussion in completely the wrong direction. Perhaps I have expressed myself too briefly or taken some basic facts for granted. So now I’ll go a little further.

The regularity or short-/long-term nature of contributions and contributors make no difference about “valuable” or “useful” contributions, or contributions at all. And at no point I said something like that. Rather, it takes account of the fact that the extent varies to which each participant contributes work. This is simply a fact and not a judgment or a division of the community.

Rather, what I was focusing on is that a successful project needs not only long/short/whatever term contributions and contributors, but also structure, planning and organization. In everyday life, this is known as “the whole is more than the sum of the parts” (probably a rough translation from German). It needs a (sub)group of participants who take care of it. And again, this is not a division of the community, it is not a special “honor” or “appreciation” of some participants over others. There is no “red carpet” and nothing glorious.

In this context, I would like to quote @smooge from the debate in the Server WG: „… 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 this to Docs, contributors, Docs Team and Docs Board in the same way.

And what happens when no one cares about structure, plan and organization can be seen in the Fedora Server Edition around 2018/2019, and in Docs and Quick Docs until about 1 1/2 years ago. Quick Docs became a collection of documents of dubious quality, mostly outdated, without reliable action value, unclear which document might be useful and which not. The work of many individual contributors was wasted because the usefulness of their work was thrown into considerable doubt by the context of the Quick Docs collection. The whole project became unattractive and the number of contributors dropped continuously.

To summarize: We need both short/medium/long/whatever term contributors and contributions as well as a group ‘committed for N hours a week to whatever is needed to publish documentation and specifically quick docs articles of high and lasting quality’.

So please @ankursinha and @hankuoffroad continue to contribute as you did and as you can. There is nothing to feel excluded or not welcome. But, please, don’t fall into spontaneous individual actions that involve planning, structure and organization without consultation with those who take care of it. That’s what we have the Docs Board for. The work is already difficult and time-consuming enough. Or even better, join those who take care of it, i.e. the Docs Board. See Documentation Team Charter.

Quick admin prefaces:

  1. Changed category.[1]
  2. Changed title.[2]
  3. Paused topic until 2023-12-19T08:00:00Z.[3]

Hi folks. I suggest we take a deep breath and pause here. We are no longer on the original topic (a Discourse bot) and I worry there is talking past each other. I preface this with a reminder about the Fedora Friends Foundation:

"The Fedora community is made up of people from all walks of life, working together to advance free software. There is a place in Fedora for anyone who wants to help, regardless of technical skill level, as long as they believe in our core values.

Like any friends, we occasionally disagree on details, but we believe in finding an acceptable consensus to serve the interests of advancing free software."

I know personally that the people replying in this topic care a lot about Fedora. We care about doing quality work. We care about collaborating together as an open community. We care about contributing to Fedora being enjoyable and not painful. Somewhere along the way, there seem to be disagreements on how to keep up with the best ways of doing good work, collaborating together, and keeping it enjoyable.

I have short-term and long-term ideas on where we can go from here.

Looking at now

Right now, I sense confusion over one is supposed to contribute and how contributing works. In this confusion, some words made people feel like their work is not valuable and underappreciated. This is a serious accusation in Open Source communities, where often we rely on the merit of our work in the community to speak for ourselves and our capabilities.

Yet even if not intended, words can have intentions we do not expect. Knowing that, let’s assume good intentions first and lean into the Fedora Friends Foundation mentioned above.

First, I request better documentation how the process is supposed to work. During the drafting process, collect feedback from Fedora Docs contributors about how to make the process work well for everyone.

Important context

The Fedora Docs Team is one of the oldest teams still active in Fedora. There is a lot of history that comes with that. The tools we used 15 years ago changed, but many git-based workflows remain the same because that has not changed. But while some things are similar to 15 years ago, some things are not.

We want Fedora Docs to be accessible both to our ongoing and persistent Fedora contributors and our newcomers. To do this best, it requires both good documentation and contributor outreach.

How to improve

The biggest challenge I see right now is documentation for the process, not the tools. I reviewed about existing docs for how someone is instructed to contribute to Fedora Docs. I checked the team’s authorship docs, team’s infra docs, and Quick Docs guidelines. The below quote from the authorship docs was the only content I found describing the process and not tools:

The 4-eyes principle applies to the Fedora documentation. A different author reviews each contribution. When you complete your text or text modification, the system creates a “Pull Request” or “Merge Request” to integrate your text into the documentation body. This triggers other authors, board members or members committed to the part of the documentation body in question, to start a review and either initiates an inclusion or starts a discussion. Allow 2 to 3 days for an answer to a request.

Many words used here describe features of the tool. It is missing an explanations for the following:

  • 4-eyes principle
  • Who are the authors, board members, or members
  • What happens in an answer/review?
  • What happens after the first review?
  • How does someone propose changes to the Fedora Docs Team that are not about documentation? What about contributions that don’t look like Merge/Pull Requests?
  • How does someone participate at different levels?

Making this information is clear for old-timers and newcomers alike. So, this is a great “bugfix” opportunity for the Fedora Docs Team. By leaving this bug unchecked, it leaves room for miscommunication and confusion. By “fixing” this bug, we can invite feedback from other Fedora Docs contributors with a clear ask and build a strong process that works well for everyone.

@pboy, could you help with this by creating a first draft of how things are structured today? A HackMD pad could be a good place to start.

Looking at later

The challenges we see here are not new, not in Fedora and not in other Open Source communities. There are challenges that come from keeping up with the best ways of doing good work, collaborating together, and keeping it enjoyable.

I have two longer-term pathways forward that could help support the Fedora Docs Team in 2024:

  • Community Operations 2.0: The Fedora Docs Team should fully own thoroughly documenting their contribution process. But outreach should not be the team’s shoulders alone. Community Operations 2.0 could help the Fedora Docs Team by promoting the updated contribution process in various contributor channels and increase awareness about how and where to get involved with Fedora Docs.

  • Reviving Fedora Mindshare Committee: We need a strengthened Fedora Mindshare Committee with incoming feedback from the Docs Team. Through this topic, I learned there is a Fedora Docs Board. I am hesitant about Fedora Mindshare teams creating their own boards to manage change because this was the founding vision for the Fedora Mindshare Committee: a common group to coordinate decisions among non-engineering Fedora teams.

So, this is a good chance for us to check in and ask, is the Fedora Mindshare Committee working as designed? If not, in what ways can we redesign it for 2024 and make it work well for everyone? We could consider an in-person Fedora Hackfest to enable this too.


This was a lot of text. But I know folks here care about Fedora. So I am doing my part by giving my care that this discussion is taken seriously and it is also something we can work out as a community.

So for now, let’s unplug from this for a couple days. When we come back, I look forward to hearing what folks have to say about making our current situation better. :muscle:

  1. I moved this topic from Ask Fedora to Project Discussion. I, too, do this by mistake all the time. :slightly_smiling_face: ↩︎

  2. I changed the topic title to reflect that we are no longer discussing the Discourse bot but instead, team governance and process. ↩︎

  3. I am pausing this Discourse topic until 2023-12-19T08:00:00Z after my reply. I chose to do this because I felt that the temperature tone of this thread is hot. I believe pausing the Discourse topic lets us fully disconnect for the remainder of this weekend, and come back fresh after a brief break. ↩︎


This topic was automatically opened after 2 days.

I’ll do that. Will need some days until after Christmas.

I think, this is already underway. (see various entries in mastodon, podcast, etc). Hank did a lot for this. We are at the beginning here, and it can (and must) be improved, for sure. And Mindshare Committee could be a great help (and a great tool) to achieve that.

When I started to engage with Docs about 2 years ago, I looked for Mindshare Comittee. But I couldn’t find something, no meetings, no working plan, no coordination of something, … I don’t know how the current situation is. My impression from the outside is, the committee currently either lacks members with “commitment for N hours a week to do whatever is needed” (see previous post) or a plan or a specific goal what you could commit to (or both) or needs to improve visibility and approachability.

That would be really, really great! But it is probably rather a challenge to accomplish.