That was my first reaction when I first saw the Docs website. Over time, I got used to the status of fragmentation[1] and justification (sort of?).
Could workstation-wg share views on this?
Please check this thread (2022) that might help you understand how Docs approached information architecture point of view.
that led me to skip “Workstation” and “Fedora Linux” section altogether" knowing which pages are abandoned. Use built-in search window ↩︎
FWIW, I personally am on record as believing it is ultimately better to let them, than for every new contributor to contribute a new fork of the documentation platform/backend.
People who genuinely want to contribute are, in my experience, mostly willing to contribute in the correct way — meaning, using the appropriate tools/systems — provided someone is able to explain to them what that correct way even is. (It may be that we’re collectively failing on that last point, more than we are failing to attract contributors willing to work within existing structure.)
And people who want to contribute technical documentation, but have an aversion to all things technical, should not be writing technical documentation. (Purely IMHO.)
I’m sure many long-time Fedora users get used to it over time. My worry is with first-time Fedora users, whose first encounter with official Fedora resources is via the home page. There they can find an elegant and professional-looking website (kudos to the team), yet a couple of clicks away they land on Fedora’s main documentation page, where they suddenly become confused and probably can’t explain the setback.
The survey in that thread is as valid today as it was 2 years ago. I think it’s better to have content completely removed than to keep it outdated. I don’t consider such actions to show lack of respect and appreciation to the contributors of those (now obsolete) pages, even though I start to believe this might be one of the reasons why these pages are still there.
This approach could work when there are lots of contributors to choose from. Yet when we’re facing the lack of volunteers, we need to adapt. It’s not that the volunteers get to choose the tools, but it is good to listen to their needs, as to be able to provide those tools (and procedures, sets of rules) which ensure higher adherence.
Overall, in response to the issue raised by this topic, I think defining one centralized documentation team/body (as opposed to different WGs and SIGs) would help correct the current fragmentation issues (and redundance, obsolescence) in documentation.
See, but I would argue that the fewer contributors we have, the worse it is for everyone to be doing their own thing. Worse for the contributors, and worse for the project users, who then have to deal with… well, see the OP.
Beyond that, I think we’re in agreement. We need a centralized documentation effort — both in terms of its organization and its content/output — and that effort needs to give potential contributors direction on how they can contribute if they’re so inclined.
But what it needs to NOT do, IMHO, is either convince “itself” that the problem is the process, or believe every contributor who says, “Oh, I’d write all of your documentation in a month, if ooooooonly I didn’t have to deal with {git, asciidoc, Pagure, Antora1}.” Spoiler alert: They’re lying! Whether they realize it or not.
This is admittedly wandering more than a bit off-topic, but speaking of Antora: One thing I think docs contributors could use, from a technical standpoint, is a way to easily preview their work without having to rely on Antora, while still using all of the same rendering tools, stylesheets, etc
Because right now, when editing .adoc files for docs.fedoraproject.org… sure, you can preview them using whatever asciidoc conversion is built into your editor, but they’ll look almost nothing like they will on-site. It’d be nice, when previewing changes, to be able to do a local, static, reasonably-site-accurate build of the docs content as a whole.
Obtaining a representative local copy of the rendered docs currently involves getting Antora running locally. I lost a week of my life one afternoon trying to do that, and ultimately gave up because I’m not THAT much of a masochist.
But it is theoretically possible to achieve a middle ground where content can be rendered “[almost] like on the site”, without being on the site. It just requires that there be some way to do the same HTML conversion, with all of the same content resources available, as are used by the Antora server.
Unfortunately, as things stand quite a lot of Antora’s rendering pipeline and document/resources configuration is all but hardcoded into it. There is technically a modular “theme” definition (the UI bundle that gets built from antora-ui-default), but it’s coupled enough to Antora itself that it’s hard for anything but Antora to make use of.
Still, it might be worth the development effort to come up with, and document, a way to obtain and use an extracted — and (even harder) kept in sync — form of all that which can be executed locally on any Fedora system, as the basis for a Docs preview tool.
Added workstation-wg
Good site!
This with some text and some updates would be great
As @smooge pointed out, we have indeed a fragmentation of tools and for good reasons.
A kind of de-duplication at the level of the tools and also the repos will only be possible to a very limited extent. Instead, “de-duplication” is needed at the content level.
The docs landing page is an attempt to achieve this. It is certainly expandable and improvable, I made a suggestion some time ago, but got only limited response. And as a supplement to the general Fedora introduction, a “Where to find what” page would certainly be helpful. However, it will be a challenge to keep this page up to date.
Another point would be to improve our home page. I had suggested in another thread to replace “Help” with “Info” to give better and more accurate access. But obviously the “helpers” want to keep “Help” as their project.
Of course, what we could and should do is to promote and advocate our primary tools, e.g. encourage people to switch from wiki to AsciiDocs/Antora.
There is a new poll for this. Not many voters yet though.
I like your docs page!
I would change “emerging desktops” with “atomic desktops” though
It may be based on an older version of the docs?
Yes, it is nearly 1 year old. So, yes, we would have to update the descriptions to the current state.
Have you watched keynote presentation from Matt Miller yet on day 1 of Flock to Fedora?
We know it is hard not to be confused by the current state of Docs and other knowledge base. Above is a diagram of an ideal future state (work in progress - very early).
This one is great
Actually, just having something is great. No matter if it is apps.fedoraproject.org (updated), or @pboy’s website (updated) or a simple infographic like that.
i should update myself — thanks to Docker and container registries for things like Antora images, sometimes we DO have that already.
A Quick Docs editor can do this:
git clone https://pagure.io/fedora-docs/quick-docs.git
cd quick-docs
./docbuilder.sh -w
And they’ll get a preview version of the Quick Docs site served from a local URL, complete with site theme applied. The server will even watch the files in modules/ROOT/ and automatically rebuild on any changes. 
…But, of course, because of… basically everything discussed above, the same thing doesn’t work everywhere.
https://pagure.io/Fedora-Council/council-docs.git, you have to run ./preview.sh instead, and you get a decidedly inferior local server. (Doesn’t watch changes, uses a hardcoded port number that has to be free.)https://pagure.io/packaging-committee.git, you instead have to run make serve — but only after you’ve run make! — and you get a preview on a (different) fixed port number, with a version of the theme that doesn’t include dark mode, and may be lacking in other ways.Docsbuilder script is maintained by the Docs team - see this repo here to track the latest changes.
Based on the Quick Docs repo, docsbuilder itself seems great. We just need to get it standardized to all of the docs repos, now!
You might find a related post about CI config files and pre-commit checks across repos.