Fedora and CentOS Docs Revitalization

Project Discussion
1

Problem: The Fedora Docs team is currently unstructured. New contributors don’t know what to work on, and there’s no clear method for making site-wide decisions. The CentOS Docs team lacks sustained contribution.

Goal: Create a unified Fedora and CentOS Docs team that is self-sustaining and community-led. Specific measures of success:

  • Regular meetings of the docs team to coordinate work
  • Community-selected team lead(s) by 1 July 2022
  • An onboarding process for new contributors
  • Development and documentation of common attributes
  • Improved documentation of style and tooling, including build process

Other nice-to-haves:

  • A hackfest to update and curate existing documentation, build relationships on the team
  • Development of a script to wrap the docs build/preview process
  • Migration of docs source to GitLab
  • Retirement of unused repositories
  • Broader and earlier contributions to Fedora Linux release notes

Q&A

Who will lead this effort?

@bcotton and @shaunm will co-lead this until a community leader is selected.

Will team members be required to contribute to both Fedora and CentOS documentation?

No. They will be welcome to, but as always contributors can contribute where they like.

Why combine Fedora and CentOS Docs teams?

This reduces the overhead of running two teams and makes it easier to coordinate docs across the communities.

Will Fedora and CentOS share all docs?

Fedora and CentOS will share docs where it makes sense. Some docs may be entirely common. Others will branch for CentOS the way packages do. The Venn diagram may overlap, but it’s not a circle.

How do I join?

Follow and participate in the docs tag on Fedora Discussion. Fill out the meeting time survey by 2 February so we can schedule regular chat meetings.

6 Likes
2

This is the general plan, subject to change as we figure out what works and what doesn’t. Your input is welcome, of course. This is not a dictate from on high, just a starting point we can work from together.

3

Hi Ben,

Thank you for bringing this up.

I think it is a good idea since Fedora Docs is being revitalized to bring CentOS Stream along in order to combine efforts. Do you have any specific strategies in mind to assist different projects differently during this process though? What I have in mind is that different projects may have different needs, which could become “messy” as time goes by. So I’m curious about what you and Shaun have in mind when it comes to defining what can be discussed separately or together, how will communication happen, etc.

I really appreciate to see this point here. Maybe it would also be nice to include a detailed workflow process to make the first contributions (like a reference guide), especially for folks that are not that familiarized with the tools being used.

Great idea. It could be interesting to have some seasonal events (like every quarter or semester maybe) to focus on pain points in the documentation. Maybe come up with some of them and vote for what should we tackle next, so that we can cover areas that require urgent/more attention.

Quick question: do we currently have any kind of recognition system/program for docs contributors? Maybe it would be nice to have if we don’t.

1 Like
4

That’s hard to answer right now, as we’re flying the plane as we build it, so to speak. We’ll have to figure this out as we get going. But the intent is to have this be a single team, with people contributing to the docs they want to contribute to. If it turns out having a combined team is unworkable, we’ll separate them.

There are some Fedora Badges for docs. Some of them no longer apply. What sort of recognition system do you have in mind?

1 Like
5

I don’t have anything in particular in mind, maybe some recognition award for contributors that were key for challenging projects or giveaway some swag for folks that participate in hackfests. This can be discussed further in the future, but my idea is to keep everyone engaged/motivated to restructure docs. :slight_smile:

1 Like
6

Hi Ben,

I hope for a success of the initiative from both of you. Your description of the current situation is absolutely correct. Also my various attempts at improvement over the last few years have always failed due to the lack of any communication and responsible contact persons. And the list of open and unprocessed issues on Pagure is an objective measure of failure.

In any case, I have entered my appointment options at whenisgood. Although, the click counter for the link is not very promising right now.

7

Now, that we had our 1st docs revitalization meeting, some unsystematic thoughts / ideas about it.

(a)
Is there a systematic location where we can access meeting summaries and minutes to look up meeting details? As Server WG, we keep a simple list of dates and links at the bottom of our home page. Quite helpful to show progress (and keep track of it).

By the way you find the summary of our first meeting here and the full log here.

(b)
Much of the discussion was about technology: PRs, CI, repository structure, etc. I didn’t count the words, but estimated it was 95% about technology (and some design) and 5% about content.

I think that is a mismatch and wrote: “…without wanting to be negative: Before we build CI, we should have something to distribute?” That was certainly a bit overstated (@pbokoc sorry, didn’t want to offend someone). But the situation is not that we would have a bunch of content that we can’t publish because our current publication queue is overwhelmed or inadequate.
It’s more the other way around. We already have a solid working production line and a nice design, both sitting around desperately waiting for something new to do. There is certainly one or the other thing that can be improved, but there is nothing that works insufficiently or is in urgent need of improvement, before we are able to publish new content, restructure or update existing content.

Technology and design are obviously less tedious, show success more quickly and are more pleasing overall. But we have to be careful not to get completely distracted by this. Improvement in technology and design are currently comfort zone and “nice to have”. Content, on the other hand, is insufficient and obviously the tedious work, the uncomfortable, “dirty” zone.

To prevent any distraction, we should dedicate one of the next meetings exclusively to the content and repeat this regularly.

(c)
Looking at the number of participants in our resuscitation meeting, we should urgently start an onboarding process.

A first, relatively simple step would be to increase our visibility. Docs page needs to be visible right from the home page, in line with Engineering, Mindshare and Diversity. And we need animating text that attracts users and new contributors. (Box Program Management should be more in line with Council, maybe putting the “Fedora Project” box full width, beneath 2 boxes Council and ProgMan, then the aforementioned 4 boxes. Well, in growing in a kind of “deserts of boxes”).

Next, let’s see if we can improve support for typical authors (i.e., not programmers). For example, the listed editors are good for developers, but rather strange for typical authors. Something like AsciidocFX would be more appropriate. For this, one could perhaps develop a preview adapted to Fedora, which makes a local podman superfluous for authors.

And from feedback I got from some authors of Server WG we should consider to detail git handling.

Thanks for reading that long text.

2 Likes
8

I’m not very deep into the docs issue and organization yet (I was not aware that it is so critical). But I think it makes sense to first focus on how to organize the team and how to organize the docs, and align both to each other? That facilitates effectively producing structured content. Although the meeting summary looks a bit like it focused only on organizing the docs? Your (a) question supports that perception a bit :smirk: (btw, GitLab has some tools that could help with organizing such issues)

However, if you want, I can join the team. I would be happy to help to get the docs back on track :slight_smile: Currently, my contribution is widely limited to ask.fedora.

But if there is interest, I will have to get familiar with it first.

9

I think pointing people to Meetbot is probably sufficient. The less we have to manually add links to a page, the less likely we are to forget. That said, starting a new Discussion thread for each meeting’s agenda ahead of time and then posting the links to Meetbot afterward seems like a reasonable approach. I think this warrants a thread of it’s own, so I’ll start a new one for us to discuss this topic specifically.

There’s a little bit of a chicken and egg problem: it’s hard to produce the content without the tooling and processes for it. That said, this team has two related but non-overlapping responsibilities: the docs content and the docs tooling. (Perhaps in the future, we could separate these out, either as separate teams or as “sub-teams”)

That said, I agree that we don’t want to over-focus on the tooling. We need to make sure we’re not ignoring the content. Do you have specific ideas about what content conversation in each meeting would look like? (e.g. talking about content to add, content that needs to be edited, etc etc)

I agree that we need to improve the onboarding experience and that we need to redo the front page of docs.fp.o. I disagree that Docs should get special billing there.

I wrote the Git for Docs Writers instructions after having a few conversations with interested contributors at Ohio Linux Fest, but there is much more we can do to improve our onboarding. I’m not in a good position to identify that, having been involved for so long that I’m no longer aware of what I already know. :slight_smile: This would be a good way for you to contribute, @py0xc3. In any case, it certainly warrants a separate, focused discussion.

10

Hi Ben,

I absolutely understand that. Maybe my unexperienced perspective can add some incentives of how it looks like to get in. At first, thanks for the link! That’s indeed a great and comprehensible guide. However, my issue is less how to handle git but to understand the organization (among and within repos, and workflows), which is a bit unclear to me. Nevertheless, your guide contained a very important information for me: the link to the quick docs guide repo, which guided me to the Group fedora-docs - Pagure.io . This was the “initial” overview I was seeking. However, I saw that some guides of the docs are not in this group (e.g., minimization, which relates to Fedora Minimization Objective :: Fedora Docs). The latter does not belong to a group at all. This leads to the question of what belongs to “the Docs” in terms of our responsibility. Is it just the pagure group repos or all repos that relate to docs.fp.org? If the latter, how and where get things aligned to/organized among each other?

In terms of the workflow: has every change in a specific doc/repo to be scheduled/discussed in advance, e.g. in a meeting? Or is it intended to directly make a change if something comes up and push it upstream, to be discussed after pushing? Or is it decentralized decided by the respective maintainer?

These are the issues I had in mind at first glance, looking forward to the meeting!

11

Without wanting to be pushy or petulant, the situation is not that we have “content without the tooling and processes for it”. Rather, we have conversely “tooling and processes for it without (new or updated) content”.
There are great ideas to improve tooling and processing. This is very good, and we must not neglect it at all. And I don’t think splitting into subteams would be a good idea.

Perhaps a workable start would be to alternate our meetings between tooling and content.

Hm, I don’t understand that remark. What’s wrong with listing the docs team in a row with, say, Mindshare and Diversity? The relevance is certainly the same, at least. And in terms of relevance, docs is currently our biggest weak point compared to other major distributions. And I would very much like to catch up.

Thanks for that! It was very helpful for me to start Server documentation and to get some authors on board (unfortunately just temporarily). But we have indeed a kind of “chicken and egg” problem here, specifically if we want to onboard dedicated “writers”, probably without programming experiences. Together with copperi I tried to write a somewhat more detailed guide for authors, especially without prior experience with Git. It’s certainly not perfect, and we are currently working on an addition to use branches for an article. But in my opinion, it is going in the direction we should go.

12

Hi Christopher,

Your experiences, as described in your previous post and here, exactly match my experiences when I started to increase my involvement in Fedora again after a long period of abstinence, in my case in the Server Working Group. It applies to pretty much all areas in Fedora. In Sociology, we call this a “distinctly idiosyncratic subculture” , which is characterized above all by the fact that it appears to be closed off to the outside world and there is little growth in new members. And in the long term, such a subculture dries up and disintegrates.

But that’s just a casual side note

You are addressing an extremely important fundamental decision.

In principle, I think a prior (planning) discussion is necessary. This applies in particular to extensive changes. My impression is that there has been no prior discussion in recent years. And in the meantime, this is also noticeable when looking at the documentation.

And as an author, I don’t go through the work and time to update or expand an article without knowing that, in principle, this will be published.

13

What I’d like to see is that new contributors make contributions via pull request that get reviewed asynchronously. Experienced contributors make small contributions at their discretion. Only the big changes would be discussed and planned in advance. So even in the new contributor case, if the changes they’re making are small, they don’t need to pre-discuss if they don’t want to. (e.g adding a new paragraph to explain why systemd needs a certain argument to do $thing doesn’t need pre-discussion. Rewriting an entire section of the Installation Guide would require a general consensus from the group)

1 Like
14

Organizationally, they’re not the same. Mindshare is a higher-level category. If we add Docs alongside it, we should also add Websites, Internationalization, Design, etc, etc, etc.

At any rate, this is enough of a tangent to warrant its own thread at this point.

15

Although I missed the initial meet and lots of discussion on this thread on time, I have suggestions along with two criteria for users who will find Docs as one of the key considerations to choose a platform/solution. For community-driven projects, the documentation is a deciding factor (among others like expert reviews) for user choice and inclination to a certain distro/Spin.

  1. Docs of other communities comparable to Fedora for benchmarking:
    Have we done this before? What do you think about benchmarking? What is considered best in class?

I think this approach takes out of the complexity of carrying out user surveys, which appears impractical.

  1. Docs that are easy to find what users expect: To encourage self-help to get on with the job (category/structure, ease of navigation/search by tags), what sort of structure can we consider?

Examples here to illustrate what I’m talking about (not because they are superior to what we got :slight_smile: )
Tree: typical table of contents or navigation bar
Icons: Raspberry Pi Documentation

Probably everything I do or propose as projects at work is based on user/device data and user/market survey. I’m pretty sure we can adopt a similar thought process and accelerated decision-making.

16

As far as I remember, nobody did that in the past. And I’m afraid the result would not be surprising and actually we already know it.

Currently, we have the tile design available. I guess that the design at that time was not meant for such an extensive amount of information as we have now, and as it will probably continue to grow. The situation was different then.
Another limitation is that the landing page does not only refer to user documentation, but also to documentation of the distro organization, community, etc. Optimal presentation and structuring of this content is probably very different from the user documentation. Both classes of content on the same page has its advantages and disadvantages.

Currently, a project is underway to fundamentally enhance the design and structure of the Fedora web pages. There will be a lot of changes. But it will not happen so fast. At the moment, we have to see how to make the best of it. We could improve clarity and findability even now, especially by adjusting the information in the boxes. The design itself is solid and flexible enough, I think.