Please take the time to read this if you are somehow related to any development or maintenance within Fedora and if your work has any direct or indirect relations to any type of documentation (not just Fedora Docs), or if you care about the institutions that govern things in our community. If you ever read one of my “essays”, please let it be this one.
We all know that “lazy approval”-based “rough consensus” and interpreting every response “the most positive way” are major institutions that shape Fedora. In most cases, both are vauable instutitons that create a constructive environment and, to stick with our values, friends.
However, just like everything, they have a dark side as well: the combination of both can facilitate closed systems within the open system, based upon planned economy far away from competiton & demand of Fedora and the wider Open Source communities.
Why is this the case? Because the outcome of these two instiutions does not always imply “I agree” or “I refrain because I’m not expert in this topic” → it can also imply “I do not care (anylonger), but I don’t tell you (in order to be nice)”.
We all know for long that the technical docs that are managed centrally (supported releases, quick docs, rawhide) are obsolete, partly for years. Fedora does no longer support 32 bit. Fedora 21 install screenshots are far away from current releases. Root is no longer obligated (and I do not need to set up the root account twice during installation: this is mentioned twice only because the guide jumps between different releases & editions; down to Fedora 21). Just as examples.
Some time before I joined docs, it seems that there had been an alternative for the devastating install guide put into discussion, being distributed to SIGs and related groups in order to replace the current install guide. The feedback was interpreted positively… However, the content is transferred 1:1 without changes. Only the structure was adjusted: therefore, it keeps preparing the “potentially 32 bit” Fedora boot media and goes through the 3 choices of the old media writer (of whom none exists in the current 4 choices in the current media writer), and in the end, the alternative has a hard cut: nothing more after preparing the boot media → the final pages are simply removed (which at least removes some of the later issues). But can an unchanged, still-obsolete boot media guide without installation part be any type of solution?
This leads to two questions:
→ Was there critique on the structure of the guides, which indicated this to be more critical than the content?
→ Why have these issues been ignored in the positive feedback?
The answer to both are widely the same: The centrally managed docs are a closed planned economy system which does not have to compete. This system has a one-way function to the outside world and a pre-defined interpretation of the absence of resonance: “We agree”. I doubt that there was any technical review of the proposed alternative. I assume the reason for the absence of review was a lazy approval rough consensus that did not imply “We agree” as it was interpreted, but it implied “We do not care (anylonger), we do our stuff elsewhere, but we don’t tell you to be nice, but have fun!”. However, people in general seek confirmation of their opinions (and instinctively look for it where they are likely to find it), and unless opinions become challenged by others, they become self-confirming prejudices and can even split communities: both sides assume their prejudices for granted and lose the awareness of the other sides - and they drift more and more away from each other. This has happened here, and this explains the focus of the docs which has nothing to do with the demand of the community - and this is not the fault of docs but the product of our “community’s agency”! I think I am now in the docs since about the beginning of the year. I don’t remember technical content to be the case in meetings, including the seemingly approved alternative for the Install Guide (this alternative is now in some respects even behind the current obsolete Install Guide because the alternative itself remains fully unmaintained since its discussion). Ain’t this somehow indicative?
Why doesn’t competition enforce a solution? Simple: it gave indication that it simply does not need the centrally managed technical docs pages in the way they are because Fedora is different to other projects. People can go upstream in many cases: we don’t modify upstream as far as possible (and despite that, Docs never established ties upstream). Users who are not sufficiently advanced for that have created a competition that seems to end in ask.fp, not Docs. Generic Linux issues like dm-crypt are tackled in Arch Wiki. In short: competition always solves its problems, and it does it very efficient and fast. The docs condition is unchanged for long, and this should make us ask questions.
Given previous discussions: is all that the fault of git? No. Git is used in many well maintained Docs including our upstream. I would say Arch Wiki is a rare exception, and this is because of the different structure of the Arch community & its project which cannot be compared to us. Those who need to maintain the Docs are aware of how to use git. As Ankur said in a previous thread, there was a try of a wiki instead of git (I think this was long before my time in Docs), and it didn’t work out either: because people do not engage in responsibility for Docs pages they don’t need. They go upstream. And since we have also focused less advanced users, we created ask.fp for them. The approach of “everybody is responsible for everything” was finally the bankruptcy, because this approach has in general never worked (it implies nobody is responsible for everything), and this is not how open source works: there is a reason why we don’t do this in packaging and other critical fields. But this approach helped to keep the dream of the huge Fedora Docs alive without challenging it. And whenever this point was, it determined the beginning of the development towards a closed system. I guess this is also the foundation of the devastating “everything keeps online until we have something better” → this policy in a closed, self-confirming system removed any need to focus on updating content. And it is hard to become aware of the state of a system if people are themselves part of this system.
Imho, the community has made a clear consensus about the centrally-managed technical #Docs: We don’t care, but we have resigned and don’t tell because we want to be nice. And the outcome is that the community refuses the docs something that should be a basic right: the right to be challenged. This also belongs to keeping community. When talking to fellow Fedorians about the docs topic, I sometimes have the perception the Docs are the “funny crippled mascot”, with an underlying joke of “Fedora ain’t Fedora when Docs have value” (e.g., in some conversations at conferences). The “state of Docs” is already taken for granted.
Indication for the consensus of the community is ironically the fact that Fedora still needs some types of Docs, although not in the way provided by current #Docs: An install guide for new users is definitely something competition demands! So, as this is necessary, one was created and the docs seem to have been not even involved in it at all. If my interpretation of recent threads is correct, it seems docs is not even aware of the install guide that is distributed (e.g., printed for distributing on conferences). However, although this external guide is sufficiently generic to remain somehow usable, it is as of 2018 as well and could itself need some revision (but its approach is one that seems to fit much better to what new users need).
So, what types of docs seem to be necessary centrally in Fedora? Is there still a task for docs? What does competition tell us? What does appear automatically + get maintained without us trying to enforce it by planned economy?
Specialized Silverblue (I don’t differentiate between Silverblue and Kinoite in this topic) and such need dedicated documentation to get into it: this remains maintained because it is necessary! Upstream cannot do that.
Also, information about the Fedora community, our Charter and such. This is necessary and it does not need much maintenance. Although the latter fact leads to a lack of data that gives indication, there are still users who indicate to read it (directly or by possessing the contained knowledge).
Also, it remains necessary to have a framework in which we can present all this: the Docs page docs.fp framework remains well maintained.
So the docs team keeps contributing with something that is needed by our competition, as it is involved in at least the latter two points.
But the technical documentations that are maintained centrally are simply obsolete, and competition made it’s choice: get rid of that (Fedora 35, 36, rawhide/main, Quick Docs). Technical documentation happens somewhere else with some minor exceptions (elaborated later). It simply reduces the trust in all the other Docs that remain important: Silverblue, The Fedora Project, …
Also, there remains a need for some other things, which remain used: dnf upgrade steps are something that has to be remembered twice a year, and it is one of the few pages that remain at least partly maintained. However, its trust remains challenged as well by its obsolete environment.
Another thing we need is a usable Install Guide, where we have an external version which lacks maintenance but that remains usable given its abstract approach. However, the usable one has no relation to the docs and it keeps indicating that the majority of Fedorians are advanced, and don’t have the immediate need to engage in maintaining it regularly. Consolidating efforts and responsibility might help here.
What to do now?
First, please community, make a decision, and do not do it the “Don’t care don’t tell” way, but the real Fedorian way which we also regularly put forward in packaging: if you want to have it packaged, take the responsibility and engage in it! Otherwise, let it be, don’t encourage and don’t make it undermine the remaining efforts… Identify the real demand from docs and focus this! This cannot be done within the closed docs system.
What demand do we have from a central docs element (based upon my limited perception)?
-
A technical framework for presenting Fedora-specific Docs like Silverblue, Charter, etc. → I think, Docs makes a good job in providing this! And this task is practically allocated and well maintained (which indicates the demand)
-
The non-technical pages. Council, mindshare, legal, … as far as these are not maintained by other teams; also, sometimes it seems other teams need support.
-
We do not need dnf Docs because dnf has everything upstream in a comprehensible way. But something for the average Fedorian has to tell him about how to upgrade! This is not much! The remaining is done by upstream Docs and ask.fp. There is no need for more (it is the same for many topics…). We have to identify a maintainer for this page, and maybe limit it to what is needed: it can be questioned if everything on this page is needed… a simple “upgrade guide” might be sufficient and easier to maintain. More detailed Docs around dnf and such are upstream (and help about average commands for beginners is at ask.fp; a “dnf update --refresh” case is solved easily and quickly; people at this level don’t end up at Docs anyway).
-
We need general Install Guides for “the majority”, image focused, one installation for beginners focusing live images, and maybe an advanced Guide for advanced users with the everything image (the latter can be very abstract given assumed advanced knowledge of the reader; and this guide’s major goal might be the awareness that “everything” exists: non-customizable live images can be deterring for advanced users!). I know, the “everything image” is questioned itself, but we can focus that later if we agree on such a solution. These guides should be comparable to the external non-Docs Install Guide (the approach is roughly comparable to my 7-step guide): “target audience”-focused (provide what is needed for the very group: only appropriate and necessary information provided tailored to the group), not redundant (e.g., available architectures are on getfedora anyway), generic (it contains what people need, which, e.g., excludes versions of GNOME that change with each release) but still focused on the images we have, and easy to maintain (if there is no major change in the installation environment, it will be screenshots here and there to change, not more).
-
I can imagine that the Server Docs also fulfill a comparable purpose, and they seem much more up to date than the Fedora release Docs. But I cannot argue here, as I do not need them.
All this can be done in a small, summed category like “Technical Guides” or so: small, efficient and valuable instead of big, obsolete and untrusted. Maybe there is more to be added (feel free to complete my list), but let our competition indicate what we need, and do not invent demand that does not exist… It is unfair to those who then become motivated to invest their time.
BUT: We need maintainer who work upstream and keep watching the devel mailing list. A guide and Docs in general have to be prepared for the next release and keep up to date with releases. This ain’t a big issue, but it is the type of responsibility like that of a package. Only this can prove worth to be trusted over time. And any page that does not fulfill this purpose, only undermines those who do. We don’t put any package somehow in some way into our repos and hope that sometime someone will maintain it. Orphanage is serious!
By the way: we are close to both Arch and our upstream. There are interrelations to Arch anyway, not just reading their Docs. If you find something to change there, do not re-invent it but let them know! The wonderful thing at the transnational Open Source system is that it facilitates an efficient information flow from everywhere to everywhere within constructive but pure competition; it allows tasks to centralize at the entity which is most competitive in doing it, and it brought the world its first competition-based separation of powers where transparency and forking capabilities avoid monopolies and centralization of power: when it comes to a generic wiki of Linux, Arch has proven to be that most competitive point (and it serves us as well), and I do not see any need or reward in forking (or simply duplicating) it. This also counts for our upstream Docs! They also “belong to and shape” Fedora. Please, make the docs to something that also fulfills “Open Source properties”.
Before the final point one last incentive: Peter made a good point a few days ago: It it irresponsible to inspire users to still put work into the installation guide. I agree! But I would formulate it more generic: it is irresponsible to inspire users to still put work into the centralized technical Docs of docs.
Generally, I can take the maintenance of:
- “prepare boot media” part / guide: media writer + dd (so, Linux based only)
- Install Guide for live image (beginner) and everything image (advanced): I think a successful Guide will be one that the community has in common: including the printed guide maintained by marketing ? I think it makes sense to consolidate these efforts and jointly keep something up to date. I would be happy to also satisfy the needs (and get incentives from) the marketing demand around this. If we can agree on something here, we can discuss later the needs about printing and such.
What I cannot do:
- “prepare boot media for Windows and Mac”: However, someone can co-maintain and just give me (and keep maintaining) the raw text / images. So no need to know about git or so. I can do the latter.
But I will only do this if these Guides do not end up in an untrusted environment. Finally, I have to invest time and efforts, and if it is in the centralized technical Docs as they are, many will (for good reasons) automatically mistrust it.
I hope this is taken as constructive critique. I think sometimes it is necessary to be a bit more direct to facilitate some developments in any direction. I have learned that any direction is better that none. But at the moment, I think this cannot go on that way. And I think people have to have in mind that “lazy approval rough consensus” plus “take everything positive” also have their potentially negative implications. Maybe docs ain’t alone?
I almost think that exact paragraph should be placed directly in Fedora’s documentation. I think everybody sort of figures that out eventually anyway.
