The future of Fedora Docs website

Hello everyone, I recently conducted a Docs Survey, and we received many responses. This has been among the most successful surveys besides the annual contributor’s survey. Thanks to all the participants:)

Here’s a link to the survey results if you want a sneak look- https://docs.google.com/spreadsheets/d/1kAaouX1B15Z-WKEw6Cq4nY66Cuu7GSvkPLxDk3ea9q8/edit#gid=1141629822

I wanted to point out some recurring themes I found in the survey:

  1. Fedora Docs is a very basic manual that helps people with installation and setting up Fedora for the first time/ a new clean install- Adequate for basic, standard operations, needs to be more comprehensive and cover details and edge cases.
  2. The docs are sparse and redundant.
  3. People feel Archwiki is a better, robust and comprehensive alternative to the existing Fedora Docs.
  4. A lot of Fedora-specific Documentation is missing from the website. The docs have good SEO but don’t deliver to people’s expectations.- If I need general Linux information, I use Arch Wiki. For Fedora-specific information, you are stuck with a web search and getting answers from Fedora Magazine, Ask Fedora and Reddit.

Fedora docs are much more likely not to have an answer or have the wrong answer. I won’t even link people to Fedora Docs anymore.
Fedora Docs is random and incomplete. If I have a Pipewire issue, I want to be able to browse docs in the same way as the Arch Wiki, ie by topic. For specific software releases, there could be a sidebar for all major releases of that topic with the “historic” pages archived.

Seeing such results, I’m curious to understand where we should take Fedora Docs from here. I feel we need to list down Fedora-specific topics that need to be covered in Fedora Docs and then build a new information architecture for the website.
I feel we shouldn’t repeat generic information on the website if people generally go to other websites for those solutions, so maybe we need to build a niche for this website.

I’m also attaching the main buckets I’ve observed on the Fedora Docs, maybe we can start from that?

Your views?

3 Likes

Whatever we do needs to 1. be sustainable and 2. add value. To me, that suggests a small set of docs that are useful, not comprehensive. There are a lot of things we could do given unlimited capacity, but with the capacity we have, here’s what I think we should do:

  1. Release Notes
  2. Installation guides on a per-variant, not a per-release basis (this is the essence of @pboy’s work). Focus on the ISO download to first use experience, not all of the possible things that can be done over the life of the installation
  3. Capacity permitting, maintain the Quick Docs as an organized knowledge base for use by people answering questions on Ask Fedora. Not as a standalone destination.

This seems like the best combination of “what we have the capacity to do” and “where we can add value to the ecosystem”. The Arch Wiki is great and we shouldn’t try to duplicate or supplant it. If we find ourselves with extra capacity over time, we can build out on #2 above to add more content for ongoing use.

2 Likes

Hi Anushka, great work. 2 Questions, so far:

  1. How can I access the survey results without a Google account?

  2. The information architecture, do you think it is the current state, or the future you would like to recommend?

The result as you summarized are not so much a surprise, in general. But give some hints where to steer in the future. To a certain extent, it goes in the same direction that I have outlined as a structure to aim for and that we have also discussed.

Another discussion would be the relationship of upstream documentation and Fedora documentation. For example, Archwiki is to a large extent a repetition, albeit perhaps a better formulation, of the corresponding upstream documentation. Question is, how are we going to manage that?

Personally, I would favor a stronger reference to upstream documentation, at least as long as there is serious upstream documentation.

2 Likes

Related Migrate Quick Docs from Docs site to Ask? although there has never been a profound discussion about who will maintain it in such a scenario (I think there are a lot of questions to be answered if this idea would be considered again). However, might be worth mentioned at this point.

I think, the issue is not so much the location, but the curation. We have several issues with current Quick Docs

  • Partly it is not “quick”, but a way out of the difficult situation with our “Administrator’s Guide”.
  • Many contributions are outdated and need updates
  • Many posts do not take into account the differences between Fedora variants and are therefore inaccurate in parts

Just to name a few.

1 Like

I think these points are interrelated. Location can facilitate and foster contribution in some respects. The question is if we can jointly maintain it, if regulars there are interested in contributing to Quick Docs (which is linked to the Quick Docs backend+interface, where git can become a problem), and of course to only do this if we can expect on the long term that it decreases the workload for ask.fp regulars.

I don’t insist to open this topic again. I just wanted to remind about it, so that everyone can include it in their considerations (or not).

[quote=“Ben Cotton, post:2, topic:41706, username:bcotton”]
Installation guides on a per-variant, not a per-release basis
[/quote] I agree to this so much!

I think you should be able to see it now

It’s basically derived from the current docs, but displayed in a way I’d recommend

I actually don’t have the right knowledge to understand what are general docs and what are fedora specific docs, but I think what I’m trying to say is that we should keep fedora docs very specific to fedora use cases, and leave the rest to Archwiki or alternates maybe?

Care to explain what upstream documentation means, please?

About 2. installation guides, a planned Anaconda installer update may be the right time to revamp the content for Workstation Edition.

Up-to-dateness of documentation varies by variants. Server docs has revision date, which gives upfront message about the up-to-dateness.

I’m watching out for issue list in GitLab for contribution.

1 Like

Maybe this helps you: Staying Close to Upstream Projects :: Fedora Docs

It generally answers what upstream and downstream is, and also has a few notes about documentation.

E.g., for Fedora, the Linux kernel, dm-crypt or git are upstream (which includes their documentation) → dm-crypt is itself upstream for the kernel when it comes to introducing new crypto functions and such. They all go downstream and end up within Fedora. Then, Fedora and its packages go further downstream firstly to CentOS and finally RHEL - although not everything makes it to the end of this stream :slight_smile: Just as one simplified example. And of course information goes in each direction!

There is a lot to do in the installer guides: see Major changes for /install-guide/install/: much obsolete and step-by-step guides switch arbitrarily between different editions (#11) · Issues · fedora / Fedora Docs / Fedora Linux Documentation / Fedora Linux Install Guide · GitLab

As far as I can see, the advanced install options ain’t much better (I added a review issue as good first issue). I agree that it might be a good idea to start with something new for the new cockpit installer. But the question is when it is introduced. I think this might take some time.

Maybe it makes sense to shorten and simplify these pages - focus on what is really necessary and what we can maintain to establish some trustworthiness. At the moment, a user cannot trust Docs because it is unclear what is up to date and what not. Concerning the advanced install: Instead of much elaboration of advanced things, I would introduce the Everything image, which does not need much elaboration in many respects (it is for advanced users and we can anticipate some things, e.g., the content of the software packages list, or set up a network). Just as an example. Focus on what is necessary for the target audience of a specific page. Two factors that can limit the content we have to maintain.

Also, we might be more aggressive when it comes to set problematic pages offline to ensure that those which are online are really trustworthy. At the moment, I am close to say this includes much of the install guides.

Not sure if this really increases trustworthiness. There are some things that don’t change often, maybe without changes for years. The date there does not tell me if there was a review since. On the other hand, some releases introduce major changes, making some Docs pages obsolete within a day. An issue we cannot overcome so easily is that we have currently limited ties to current developments on Fedora.

However, it maybe makes sense to introduce a dedicated meeting to checkout the release notes when there is a new release, and identify changes that might affect our Docs? That might be more time effective than keep checking the devel mailing list against Docs :slight_smile:

I don’t mean freshness of documentation with timestamp gives trustworthiness.
Good automated checks on docs is enabled by content freshness reminder with metadata.

By general rules, revision history of software and documentation proves reliable indicator for maintainers involved and care put into maintaining software and supporting docs. Docs last revised in 2018 or even older have outdate screenshots of UI.

There are many packages and features that are not covered by release notes. Future-proofness works for some degree, but not every content is meant to be timeless.

Yes, I can. Very interesting! Do you have a more detailed analysis of the data? Or are you planning to do it?

I’m wondering about some answers, e.g. the usage of reddit. Nearly everything I found there regarding Fedora, was badly outdated, e.g. the Cloud documentation. Worst of all, it comes with Fedora Logo makes the impression, to be the “official” Fedora documentation.

But, nevertheless, it gives us (or at least me) some ideas on how we should sharpen and focus the Fedora documentation - and disclose that in an introduction as well.

Yes, I like it. Thanks for the work. You must have spent a lot of time on it.

Agreed, that’s what I have tried to do so far. (not Archwike, but upstream documentation)

I would like to refer as much as possible to the documentation provided by the corresponding software devel project, if any. E.g., the libvirt project is upstream for Fedora virtualization, and they maintain a great documentation. Instead of “retelling” this documentation (whichArchwiki does in large parts, although often formulated in a more understandable way), we should specifically refer to passages in this documentation and only create Fedora-specific information ourselves - and there is plenty of that. Example, instead of a large .conf file Fedora prefers a .d director, in which individual configuration snippets are located. This allows a much clearer organization.

Hm, we already decided a complete new concept of the installation guide(s). This makes many of the items redundant or must be transferred to another use case.

Do you mean the normal git “history”? It shows if there have been changes. But not if there was a review. The latter does not imply the first. There might be pages that don’t need changes for a long time. Especially non-graphical user interfaces sometimes don’t change for long. The date can be misleading in both directions: indicate something obsolete as up-to-date, and indicate something up-to-date as obsolete. However, intentional minimal changes (e.g., some change that does not appear in the output) to document a review might be a solution if the goal is to keep the time as indicator.

Agreed. But our capacities are limited. And at the moment, we are close to an implicit “everything or nothing” approach.

However, I like the idea @pboy put forward: focus more on the upstream documentation. This tackles many issues we elaborated, and it is absolutely in the sense of Fedora, which focuses on strong collaboration upstream and keep what comes downstream unchanged if possible, or in short: try to make changes upstream instead of here.

Recently I made a few slight changes upstream in the Borg documentation. I was thinking of making a page for our Docs as well, but I had not the time. However, Borg has a very good Doc, and it seems sufficient to link to there when someone wants to checkout in our Docs what backup possibilities they have on Fedora, along with links to other Docs of backup tools that are packaged on Fedora. (On such Docs pages) our job could be reduced to prepare a page where Fedora users can end up when they seek backup possibilities, put forward our packages, maybe each with a short summary, and maybe a little (and generic) comparison (e.g., which is incremental and which not and such). Of course this approach cannot be applied to all pages. We still need our install guide and such. But it would make our workload for keeping things up to date and on a high quality more realistic.

A general question we might discuss (maybe in a dedicated thread if you want): if something is widely obsolete and maybe even confusing for users (see the #11 issue), is it better to keep such a page online until we have a replacement, or to set it offline until we have something more appropriate? Reading the current guide can challenge the trust in our Docs.


Another approach I would like to mention (which might also give another perspective on the origin of the problem): On the Linux kernel, it is anticipated that if someone introduces something, they are expected to maintain it. You cannot, e.g., put a random number generator in the kernel and then forget it. It is comparable with our packages on Fedora. This is not necessarily a formal thing.

Does it make sense to introduce a comparable approach if someone introduces new pages? Assign them to those who create it? Make clear that there is an expectation? And if someone no longer can/want maintain it, mark them orphaned so that we know there is no dedicated responsible member until we found someone new? Of course we would start with a big orphaned list^^

Given the findings of Anushkas Docs survey I’m convinced we should remove the installation guide as well as the administration guide from docs completely as soon as possible. They get more and more misleading and undermine confidence in our docs and in Fedora as a whole. And it is quite the worst initial experience we can provide to new users.

We have the alternative more or less ready. Or better alternative 2, because we have no documentation for Workstation at all nor for Cloud.

For Administration Tools, we could write an interim page (and name it clearly as such) with links to upstream. That’s quickly done. It’s not much, but better as the current misleading doc, IMHO.

And it is irresponsible to inspire (or at least let) users to still put work into the installation guide. This is definitely and irrevocably wasted effort.

Absolutely agreed.

Yeah, makes sense to “re-start” with something completely new. I will close the related issues and open Merge Requests and add a comment where necessary. I think there are some, especially in those already a few months old.

However, maybe we should review other pages as well and discuss comparable decisions. I’m not convinced the install guide is a single phenomenon. But that would be something we had to coordinate.

Cool! I didn’t know we have a successor in place.

Do you mean the normal git “history”?

No.
Revision history, as an example, on the edition of user docs looks frozen in time.
Many respondents of survey have mentioned outdated content at places. I’m reiterating some pointers why that impression/user experience persist.

Recently I made a few slight changes upstream in the Borg documentation.

Sounds good. Could you share the link? I spent some time with backup tools earlier this year.

Does it make sense to introduce a comparable approach if someone introduces new pages? Assign them to those who create it? Make clear that there is an expectation? And if someone no longer can/want maintain it, mark them orphaned so that we know there is no dedicated responsible member until we found someone new? Of course we would start with a big orphaned list^^

I like the idea. Sort of docs maintainer, right?

General page: https://www.borgbackup.org/
Docs: Borg Documentation — Borg - Deduplicating Archiver 1.2.2 documentation
Git repo: GitHub - borgbackup/borg: Deduplicating archiver with compression and authenticated encryption.

The Docs source is within the git repo.

2.0 is to come with several changes especially with regards to security and cryptography.

Sort of maintainer of Docs pages, yes. But just like our packages, being maintainer does not imply to write and do everything by oneself. The responsibility can be more abstract. The absence of responsibility (not even informally) is imho part of our problem. Everyone is responsible for everything, which practically implies that no one is responsible for anything. There is a reason that types of formal/informal responsibility have risen in these fields.

Nevertheless, it remains the question of who will do it: currently, it is too much for the people we have. However, focusing on forwarding/linking to upstream Docs could be complementary and facilitate a solution on the long term!

In this respect, I would even use our package maintainer as role model. They are not necessarily the developer of the packages but they have to keep ties upstream. In our case, upstream Docs. If I would maintain a backup page in Fedora Docs, I would focus on keeping ties to the Docs of Borg and rsnapshot and so on. Ensure the links remain up to date, maybe adjust our comparison of backup tools if a tool introduces encryption, and maybe also collaborate upstream as I did in my Borg example (e.g., 1, 2, 3): sometimes we become aware of issues they might not experience/see on their level - or identify a need of functions as we have a broader and more abstract perspective: with some luck, rsync gets sha1 support for large data amounts in backups, like rsnapshot :smile:. This can be also very interesting and be fun. I would be happy to combine such efforts with my Docs contribution.

However, this is a project that needs to be well prepared and coordinated. What pages to dissolve, which to keep maintained by ourselves, which to be replaced by “upstream-focused” pages that only bring upstream links / information together and only contain generic things like comparisons.

Maybe, we could also get related maintainers (packagers here or devel upstream) or so onboard, not for Docs in general but for the pages related to them. With this approach, we could offer them a clear scope that fosters information flow also in their interests, and it does not really add much work as they tend to know their tools and when which changes happen. But in this respect we have to keep skeptic and not expect too much.