Infra collaboration issues

Very nicely put. From the 9 people who have “Ownership” of the docs repositories, there is exact just one, who regularly participates in the docs team. And from the 9 there are 3, 30%, of which participation can not even be expected, because they generally take care of the infrastructure. But not about the day-to-day work of the teams.

We have great, modern, cool, powerful tools, of whose potential we might just use 20%, but don’t even actually use those. The WEB UI, with which editing documents should be so great and easy (that was @mattdm idea, at least), has been a bust so far, too complex, too much superfluous, cumbersome, bloated and then also unstable. What a lot of time that thing has cost us.

Or something else, we have 2 open MR’s regarding design, one of which is already 3 weeks old! I think this is unreasonable and irresponsible to the community members who spend time and are committed to Fedora Docs. And this is not because of the thing itself, i.e. the CSS, but because of the tool in which it is embedded and which none of us masters and also obviously has neither the desire nor the time to deal with it sufficiently intensively. And with such experiences for new members, we will never be able to create a lively writer community.

In the end, the engineers put up a fancy tool and then slipped away. They left behind writers and also users, who just want to share their experiences, which the tool hampers and costs extra time. And several people who started to contribute in the last few months have already dropped out again. And for this we need a solution now.

Either we find someone who has the inclination and time to deal with the tool and take care of it, or we need another tool. As it is now, we will fail in any case, foreseeable. And not because there is a lack of people or a lack of interest, but because with self-inflicted actions, people and technology end up too far apart.

Let me shed a light on the subject ‘infra collaboration issues’ that were interlaced in the original thread quoted above. Each paragraph has a unique topic, so I took the liberty of breaking this thread into five paragraphs to facilitate discussion.

Participation from board members

Docs team charter states as below.

As peer-recognized leaders of the team, board members will generally be ones to chair meetings and represent the team to other Fedora bodies (e.g. the Fedora Mindshare Committee).

Docs Weekly meeting is chaired by one board member. There is no substitute or rotation for the chair. Apart from chairing a meeting, Docs board members are expected to represent Docs team to other groups.

Reason / personal observation of risks: if current status (put all strain to a single board member) is unchanged and ignored, we will see board members go inactive gracefully or quit unexpectedly.

Suggestion: We need more participation from Docs board members. Participation I have in mind is chair of meeting in rota, assess conflicting priorities or long-term pending issues on UX/UI and design, and help prioritizing dev resources (Antora specialists).

If whatever reason board member decides to put energy on something else, please let us know you will step down from the board.

Web UI

Docs team has to work with two Git forge services - Pagure and GitLab.
For technical review and minor edits of content, we use Pagure UI to update Quick Docs. We haven’t heard any complaints about using Pagure for documentation.

At times, Docs team works with GitLab repo - Docs build and contributor guides. We hear extreme responses on GitLab experience - either a proponent or an antagonist. In most cases, proponents of GitLab repos are NOT involved with day to day operations of Docs maintenance and technical review. There are contrasting opinions between two groups.

  • Proponents: Advanced features and project management tools
  • Antagonists: Complex and overkill for documentation writing. Obstacles to new contributors.

Suggestion: I don’t really know. I wasted countless hours or even hurt feelings of colleagues to debate about tools. I’m in Docs team to get to know documentation lovers and learn by doing new things in documentation. I feel like a piggy (sorry piglet) in the middle.

Design issue tickets to prioritize

Replied on original thread. Dev resource allocation was mentioned on ‘participation from board members’ section.

Authoring tool and process as a detractor or promoter for new contributors?

I don’t think I’m the right person to comment. People who worked briefly but contributed significantly don’t become inactive due to tools. Time commitment and personal issues are known reasons for that. I know a colleague who contributed to various articles in Quick Docs and GitLab Docs contributor repos for a few months and decided to become inactive. The person liked tools Docs team use.

I’m fairly comfortable with local authoring environment, Pagure UI and GitLab UI/CI/vale linter.
It wasn’t ‘simple’ in the first place to make the first pull request to the eyes of a newbie without developer background like me. I made an effort to contribution workflow easier than before, so new potential contributors can settle in quickly.

I am adapting my writing workflow for FOSS toolset used by the community. I’m not attached to a particular tool. I just want to write technical articles and hopefully learn about pipelline script for automation, which is my personal goal to contribute more for Docs.

Do we need another tool?

I doubt it will solve a problem. Please don’t bring another tool.

This is a conversational starter, not a place to convince you with a manifesto.

Unfortunately, I cannot engage much in discussions here atm, but some thoughts I had when skimming it

The cases I remember, people kept the team informed when something happened that forced them to re-focus, and when necessary, they stepped down, no? The issue I perceive in this respect is that the interest in contribution is limited which keeps the team small (so that single members who have to re-focus can hardly be balanced), and thus the meeting sometimes contains only 1 or 2 people. Practically, the permanent team (in terms of people who are sufficiently deep involved to pick up responsibilities) is widely equal to the board anyway. Maybe I misunderstood the point?

It might be noted that the team is also a little isolated, which could be linked to multiple of the points in this topic. However, when having issues or if I needed something, I have good experiences so far in facilitating collaboration with other teams, but this has to be explicit. The recent team up with Anaconda is one example. The joint development and testing of the initial 7-steps guide in collaboration with ask.fp is another. But things like that need to include to first check out who could help, how they can help and then how to reach them and let them know about what in specific to achieve jointly and how (or find out why they cannot help in this respect and then tackle that reason). The infra-related teams are likely not aware of the issue we have at Docs. I have to admit that I ignored the failures myself since they don’t hurt, and Peter is absolutely right that we should not accept this as permanent condition, but I expect that the related teams/people will not reject us if we let them know that things don’t work that way for us and what our preferences would be (disable code_quality I guess?). If we don’t, they assume everything is fine. We cannot expect that they keep tracking our conversations and meetings. I am still not sure if I really understand the issues that led to this topic, so please be patient if I have misunderstood something :wink:

To put it casually, maybe some of the Docs’ activities could be seen as a “We have a problem” within its own docs realms, that could be replaced by “this is what you from the “abc” team could do together with us to achieve an outcome that improves/fosters both of our activities” not within docs but triggered the correct way to the respective other team. If the outcome does not improve both, Docs has to consider if that activity adds value to the community AND if it is realistic to be done for Docs on its own.

Related to the above, if people start at Docs, they are unlikely to get involved in the wider Fedora community and exposed to it. It’s like a separated little bubble that could be perceived as monotonous. When I think back on what embedded me in Fedora, it was much about being exposed to the community and regularly learn and see how efficient its collaborations and information flows can solve problems, where one can participate and contribute (and see the developments and outcomes), I think this is indeed a motivator. And this facilitates to achieve a lot of knowledge.

However, there is one thing that might be also linked to the above “bubble” issues: Docs is part of Mindshare (Fedora org), but there is no outreach in any direction, although the Mindshare representative is now also our representative. This means that the actually intended passive flow of information (about Docs, issues, plans, pleas, worries, etc.) towards the top organization where Fedora comes together is not triggered anywhere. Maybe starting at this point and creating some outreach to our “representative” makes sense? (@bt0dotninja) Just to get a bit aware of each other, and find out if and where to place Docs. This is of course not the origin of the issues but itself only a symptom, and it is not a game changer though, but a first step towards resolving the bubble, which remains imho directly or indirectly the major origin of most issues.

In the past, we once had a formal Docs representative at the Council I think, and I assume no one really thought much about it when this was changed since the representation and the actual Docs team have been practically separated anyway as far as I perceived it. So I assume no one really considered that Mindshare now also represents Docs immediately.

100% :wink:

You are right, in principle. Practically, for a few weeks now, we have only 2 people continuously working on Fedora Docs. That is both of us. We have reason to hope that Chris will rejoin when his time permits. That’s why we shouldn’t be particularly concerned with Doc’s board at this time. It is much more important that the active ones, essentially the two of us at the moment, can work as well and as smoothly as possible. As soon as we achieve success with onboarding, then the question of the “board” could become important again, I think.

Right now, I think it’s more about simplifying tools and getting rid of elements that we don’t currently need and that just get in the way.

Regarding the pipeline problem: The current problem is obviously fixed. But does that really benefit us at the moment? Should we perhaps disable it until we actually use a GitLab repository? Our focus will be on QuickDocs and onboarding for the time being. On Gitlab we will mainly work on the team pages and the guides. And these changes will mainly be done by one of us, as it looks like right now. Do we need the tool for that and the effort to take care of regular updates?

Practically, it’s just one of the board members and one non-board member. And hopefully maybe you again, sometime in the next few months. The “board” is currently a proverbial “dead horse”, an empty construct. If we want to make it useful again, we would have to re-staff it with people who are actually and continuously involved in the Fedora Docs team.

I’m leaning right now towards just keeping it all as it is. We should focus on onboarding and if we are successful in that, then renegotiate the staffing of the board.

Indeed. But to fix this needs ressources, too

A year ago we discussed to split the docs team into “team content” and “team technics”. We didn’t do that for good reason. Maybe we should consider that now, where instead of “team technics” we would dump everything at CommOps or websites. :slight_smile:

Yeah, last time I had a look onto the members list (currently the link is not working) there was a nick name as docs representative that I never noticed in docs discussions and work for the last 2 years.

But you are right, that could be a third issue we should include in our list of most urgent items.

Absolutely. Permanent & board is the same atm. However, the alternative is to get rid of separating between the permanent members and the board level, if they have proven to be equal anyway (that’s not really a suggestion, just a thought I had in mind ).

Not really. We just need to get in touch in an effective/constructive manner. The ask.fedora people imho decreased my work in creating the guide, and increased its value. What the Anaconda people provided also made the planning of the guide easier, and already avoided unnecessary work since they kept me updated (which increased the time I could invest elsewhere).

However, it of course implies to check in advance if we have the resources to fulfill our role towards the respective common goal. That’s one of the things I meant with the related who-how-questions that always need to be checked out first.

Well, it would make things easier :smiley:

No, you haven’t misunderstood. I thought ahead of the core issues you highlighted. I added my view on the number of owner privileges in Docs repo @pboy explained. I hoped more board members be active.

I’m with you on that 100%. I peeked into Join SIG group and CommOps to take some inspirations from other groups and work together. Justin is involved with Docs improvement agenda. A recent activity was release party.

Hmm, I’m not sure if this can be generalized to all Docs members. Docs UX enhancement affect all documentation repos (currently 9). There are possibilities we can harness across other groups. I have seen valuable UX improvement done incrementally over the last months (Docs UI repo), especially by @ferdnyc @darknao . I’ll get more involved with CommOps and Magazine after Flock.

What I agree with you on what’s boring is fixing docs minor issues manually is tiring and I don’t feel I can continue over time.

I have no objection to the idea if vale script does not help us now. Anyone can run linters locally.

Yeah indeed. And it is a subjective perception as well. Nevertheless, I think it is a realistic perception for several people that have appeared and then disappeared over time, and something that can be linked to existing issues in multiple aspects. E.g., when members were to update or even write whole guides with regards to Fedora tools, while they where on their own without working with the related teams. Here n’ there a little talk within Docs, but no incentives or approaches towards outreach.

What I have in mind is, e.g., that at some point a dnf guide was created by a new member, but there was no triggering towards the related team. The member did not know that something new was already on the way that made much of the efforts obsolete, and that much of what they planned was already available somewhere else (we should always remember that there are also upstream Docs that are applicable to Fedora*, to which still no ties exist, although they could be involved in solutions). At the same time, there are several possibilities to get in touch with dnf-related people. I think Docs got a little used to keep the isolation.

* in this case, DNF, the next-generation replacement for YUM — dnf latest documentation → finally, we provide an upstream focused distribution that intentionally keeps compatible upstream - and aims to maintain ties and feedback loops upstream. But so far, Docs is excluded from Fedora’s practices in this respect.

++. a passing thought…if board needs to exist, the way I picture board member is cheerleaders and ambassadors. Am i unrealistic, maybe? Sometimes, I feel we are racing without spare tyres and mechanics around. If one goes, then the race stops.

Fair enough. I didn’t know about this. Peter and I are trying to make changes to team up with other groups and on events such as release party/Flock.

Absolutely. It could be added that at the moment, the permanent members are capable to fulfill the same role (since they are practically the same level of experience). However, once leaving the own inner organization, much is about representation & to be perceived as a “formal/competent representative”, so the corresponding “industry practice” would be not to get rid of the board but to get rid of the permanent members :smiley:

Sounds great! Unfortunately, atm, I assume that I will not be able to make it to Flock.


well sounds like age-old monarchy system! What I’m contemplating is state treason?

A very accurate summary. However, if one tire goes, we’ll just do the race with one less tire - as best we can - at the moment.

I meant only the naming, to have a name that sounds representative and valuable when acting outside the inner organization :wink: So, take the same people and give them “more competent” titles (that means, not replacing people but only their titles) :smiley: Today, we have Vice Presidents that serve average consumers at financial institutes (which makes both average customer+employee feel more important). Just as an example. (Finally, a type of inflation ^^)

Back to the issues, Peter and I open issue tickets to the respective repo (Docs UI or design) and nudge usual suspect on the comments in repo. Opening a thread like this is things are getting escalated for attention. Well, sometimes issues go through the cracks. That happens.

Ain’t this our own Docs repos? Not sure if the Docs team is the right team to process that :wink:

Maybe check out if one of these two teams make sense:

Fedora Websites & Apps Team

Fedora Websites and Apps · GitLab
Fedora Websites & Apps Team :: Fedora Docs
fedora / Fedora Websites and Apps / Fedora Websites / fedora-websites-3.0 · GitLab

- OR -


Info | - Fedora mailing-lists
Infrastructure - Fedora Project Wiki

In case of doubts, I would suggest to have a short “get in touch” through Matrix or so instead of just opening tickets, that might be more a facilitator for creating ties and understanding of reciprocal needs :wink: My guess is the first team, but not sure.

Of course, my wording to “dump” it to another team was meant sarcastically - or at least an attempt of such a wording. The matter is on my todo for July.

No worries, I understood it that way :wink: My last post was not related to that but more to the fact that the issue already ended up as a ticket in a repo waiting for someone to pick it up, which is more a “passive” way of getting into interaction. Makes sense in the Docs repos, but if opening tickets in other repos, I just wanted to provide a little incentive to use more proactive means in the beginning :wink: Obviously, there are currently no ties to the team responsible for that type of issue, and I suggest to not just wait until darknao scrolls through the Docs repos. Relying on him to casually and informally do that is not a good long term solution imho.