Document the current state of Fedora Fragmentation

I saw that Fedora has a ton of duplication… which is pretty concerning.

  • wiki
  • docs
  • magazine
  • blog
  • reddit, facebook, twitter, telegram, mastodon
  • (discourse)

This is pretty crazy! Not to mention that the sources are scattered between pagure.io, fedora pagure, gitlab and github.

I would like to create a page explaining where to find what, a short explanation of “why”, with all the links.

Somewhere like on the Docs homepage. “Navigation” “where can I find the various bits of Fedora?”.


A bit like here

To help against the fragmentation.

1 Like

Hmmm, we can’t compare one documentation type/platform with others, can we? Each one serves different purpose. Wiki doesn’t seem to flourish as a documentation platform in Fedora. Some working groups have a plan to retire wiki entirely and move to Docs.

I didn’t list up shortcomings of Pagure Web UI as a reason for centralization of Git forge. Pagure is a best fit for CLI workflow. Web UI is rather pristine. Some of experienced authors prefer Pagure to GitLab.

Now I’m switching my documentation writing workflow to CLI completely, and Pagure suits my workflow.

2 Likes

For what it’s worth, I thought I’d chime in just to add another point of view, in the hopes my views might intrigue “stakeholders”.

Let me start by saying I’ve only been silently following this thread because I really appreciate any and all efforts of improving the docs with Fedora.

In the short while I’ve been using Fedora, I’ve had my issues with documentation, eg:

(note for example my attempt of finding more/better/accurate information outside Fedora Docs, with pykickstart docs)

I think I’ll simply say in other words what @hamrheadcorvette and @boredsquirrel have already stated above:

Platform Fragmentation (especially of documentation!!) feels terrible on Fedora…
As a (new) user, I wouldn’t know where to look.
As a (potential) contributor, I don’t know where to act.
So many platforms that serve “different purpose” is 100% not a good thing.

Elsewhere, discussing Fedora first impressions I’ve stated:

So many different domains and platforms for discussions, documentation, issues,
bugs, packages, meetings, stats. I guarantee new users will be intimidated in their effort to keep well informed.

I stand by that statement.
I might have said harsher things too, but I intentionally omit them here, because the intention of this post is not to get argumentative, but rather to offer some (hopefully) constructive criticism.

So, I don’t see why comparing documentation type/platform would be unfair in the context of that previous post.
If there is information that is/gets duplicated across platforms, then there is information that is either misplaced or redundant.

And I don’t have any opinionated say in regards to the tools used — I’ll leave that to those of you who actively strive to make the end product better for all of us — but the fact that me or others aren’t actively contributing will probably remain so for as long as the bigger picture remains so confusing…

Kindly,
just one Fedora End-User

2 Likes

As far as I remember,
Wiki used to be a source of knowledge base across many working groups before 2018. Check this Magazine article “Fedora’s Documentation Website has been overhauled”. Many wiki articles were converted to Docs using wiki conversion script. Wiki vs Docs is best explained in this thread.

Docs: Documentation sites were incorporated into Antora static site generator that combines different Git forge. The Fedora Project respects a decision of working groups/SIGs. Since 2022, many working groups/SIGs moved to GitLab. Still, it is confusing for new contributors why one has to work on different Git forges.

Docs articles are maintained, peer-reviewed, and version-controlled. It requires certain routines and processes that are natural for developers. For those who are not familiar with it, there is a learning curve that worth learning the ropes.

The Fedora Magazine is, by definition, “a website that hosts promotional articles and short guides”. Although some of short guides are very comprehensive and self-containing, the content that needs updating is not suitable. I don’t see overlap between Docs and Magazine in its inception. But some how-to articles in the Magazine can be found also in Docs, which looks duplicated.

Fedora CommBlog: It doesn’t publish knowledge articles. What is being duplicated?

And other platforms - even Fedora moderated accounts do not publlsh knowledge articles.

Discourse: we have been discussing this topic on other threads. I recall you will be running a poll.

Matrix/mailing lists: it is irrelevant here as a knowledge platform.

Back to the point, I’m sharing what works well in Pagure and what doesn’t after trial and error. Nobody told me. I moved on and documented the guides and removed duplication.

As @pboy shared his view on tool vs content on other thread, platform integration and preference on tools are not related to quantity and quality of documentation.

I grew out of confusion and duplication. I learned a ton from challenges faced by Docs team. Help make us less confused and dedup content. I did my part.

4 Likes

I’m only stating that, for example, some platforms cited by @boredsquirrel are not established as knowledge portal.

Yes, some topics are over documented across different Docs pages, discourse and the Magazine. Others are in poor state (untouched for many years).

Some will wither away as a knowledge platform (like wiki) in Fedora. More and more working groups are moving to GitLab. Release notes are migrated to GitLab.

We do this by stage, preparations and consensus. No one stands up and says ‘unify all platforms’.

We are short of resources. Help us.

We also share experience and knowledge by Docs workshop and other events.

2 Likes

Thanks for the heads up.

I think it would help drastically to have some kind of explanation site of the state Fedora is in currently, where to find what, why etc.

2 Likes

Some portion of the duplication comes from people running into the limitations of previous tools and trying to unify what existed already under a newer/better tool. The problem is that the old content needs to stay up but keeps getting added to AND the new team usually run out of energy.

A good portion of the older documentation was built around the idea that Red Hat would provide a core of documents and others would join in. At first these initiatives would start with a large number of volunteers and then eventually run into ‘no volunteers’ due to personality conflicts or conflicts of direction. Then there would be reorganizations inside of Red Hat which would change the teams focus and documentation would drift off.

In the end, technical documentation is very very hard. I would put it harder than coding as developers usually don’t find they can document well what they are doing without rewriting what they had done to ‘fix’ something. Having volunteers doing it is great, but it comes with the caveat that volunteers get to choose the tools they use. If they don’t want to write asciidoc but you tell them they have to… they go somewhere else. If they don’t want to write stuff in a wiki, they will go somewhere else… etc. Which means that over time you end up with a lot of little sites spread all over.

Where could the information go?
Contributor guide may not be visible as much.

If it is the Docs landing page, someone needs to make a suggestion and get buy-ins from Docs team other than me.

1 Like

I imagine some front page in the docs. Fedora infra? Not sure.

Should be general, maybe a meta-page “how fedora does things”

1 Like

Added docs-team, infrastructure-team

Great if you could list up top priority areas of de-duplication and effort required.

You took an example of Fedora Atomic Desktops and @siosm already responded with a plan on other thread.

De-duplication, for example, could be;

  • Consolidation of pages, repos
  • Archiving
  • Agree on content category by each platform: For example, we need to avoid a situation where a contributor publishes an article at platform A[1] because the person was so fed up with platform B / process / people.

Or if you have a better idea, feel free to share and let’s get buy-ins from other contributors.

I believe we need to create a sort of funnel of wish-list followed by problem statement, and group them by;

  • Doable and tangible: could be done by a single team or small group of people.
  • Must-haves but requires resources across many teams
  • Long shot: reaching for the stars

  1. Ideation, peer review and publication are quick. Process is efficient and well documented. There are regular long-term contributors around. Atmosphere is good. No need for weekly meeting ↩︎

1 Like

I dont have enough oversight about the used platforms and purposes.

Actually, that is the reason why I would like such a

Overview

How fragmented is Fedora currently?

page.

Then when there is transparency, we can talk about action points.

There are many ways to tackle and improve situations, but I’m not sure showing dirty laundry on high traffic site would encourage participation and goodwill. If you don’t know overall problems or can’t sum it up in constructive way, I don’t think we will get buy in from our colleagues.

I’m not saying this because I don’t see a problem, but I don’t want to boil the ocean for something I can’t influence.

What is documentation for you, by the way?

2 Likes

Documentation is

  1. A writeup of knowledge to help users do stuff with the available tools
  2. A writeup for contributors, like rules, knowledge, “how to start contributing” guides. Preventing loss of knowledge (aka. bus factor)

From the top of my head (might come up with more later):

  1. The wiki landing page should only consist of information that communicates its purpose and then only addresses contributors according to the context you kindly offered previously in this conversation.

    The only user facing information on it should be:

    • Explain that this page is addressing contributors. If there is need to expand further than already included in the “#This Wiki” section, then very briefly summarize changes in the thread you linked above.

    • Redirect all Users to Docs. If information currently on Wiki landing page is important, include it there (Docs) instead.

    Better contributor-facing content for the landing page could be:

    • Recently updated pages
    • Pages flagged out-of-date that could use contributor attention to be brought up to speed.
  2. Is Fedora Magazine part of the Project? If so, move it under the .fedoraproject.org domain.

  3. If the answer on #2 is yes, then it would be ideal to “widen” the “news-worthy” umbrella to include both Fedora Magazine AND community blog. It would also be more visually pleasant to unify the visual identity of such domains and everything else (eg follow the style/look-and-feel of the Fedora Project Landing Page. If clear separation is needed, it could be applied to site-level/category separation.

2 Likes

Agree!

That’ll do. Good structure.

See also: Fedora Apps

2 Likes

That’s right and I wholeheartedly agree with ‘preventing loss of knowledge’.
Make it ‘convenient’ to contribute.

I believe there should a boundary to what we must do and what not, to manage expectations. In Fedora package source, there are several thousands RPM packages. Do available tools mean everything or packaged maintained by Fedora Project or Red Hat?

Often I hear “go to upstream” by long-term contributors, which I learned the hard way. Unless the user knows problems are caused by a single application of upstream, “go to upstream” is sort of gatekeeping and barriers.

1 Like

There seems to be a high level of fragmentation and duplication also inside the Docs.

Quick Docs seems to be one of the most comprehensive documentation “modules”[1], so the name doesn’t do it justice.

Then we have Fedora Workstation, which is extremely modest regarding the information provided, and mostly covered by Quick Docs. Quick Docs is more or less the documentation for Fedora Workstation[2].

The Spins and Labs module is a just a page with links to the corresponding presentation and download pages on Fedora’s main website.

I would love to see most of these modules (the ones within the “User Documentation” section) under one umbrella, with all the modules (Workstation, Server, CoreOS, Atomic Desktops, Spins etc) as main chapters within the same documentation.

I imagine this is hard, given that each of these docs are maintained by different WGs/SIGs, but I guess it is doable, as Antora does a pretty good job of presenting these pages in a similar way from a UX perspective[3].


  1. For lack of a better term. ↩︎

  2. " The one that you’re most likely interested in, and the one that we’ll be focusing on, is Fedora Workstation" - quote from the Getting Started with Fedora page within Quick Docs. ↩︎

  3. Even if maintained with different Git forges. ↩︎

2 Likes