Please read: Fedora lazy approval, rough consensus, and its devastating impact on Docs

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?

3 Likes

I see many have already read this post, but no one has replied. As one of the participants of the originating discussion, I’ll make a first cut.

When I read the post, I was a bit “blown away” by the mixture of immense commitment and a huge misunderstanding. On the other hand, I think such a mixture can also quite easy be cleared up constructively with a little patience.

The main subject of the post is a criticism of the existing, centrally maintained installation guide, combined with the suggestion that it would be better to do without an installation guide maintained centrally by #Docs (including other central guides).

There is no disagreement at all on this point!

The structure, which the Docs team has put up for discussion and would like to implement, realizes the following criteria or principles:

  1. Away from a uniform installation and administration guide to variant-specific guides.
    Accordingly, the mockup for this new structure does not contain an installation guide, but a section “Getting started”, which lists the existing variants, briefly describes the objectives and links to the variant-specific documentation.

  2. In addition to variant-specific topics, there are also areas that are common to all or several variants. An example of this is the creation of a boot medium from the distribution medium (“Mediawriter”). Such topics do not have to be documented for each variant from scratch, but this can be done centrally.
    For this type of documentation it is decided to implement each self-contained text section as a “partial”, i.e. as a text element to be included in other Antora text items. This opens up 3 options for variant-specific documentation:

    (a) You can do without it completely and rewrite everything from scratch.
    (b) You can rewrite parts that are specific to the variant and include other parts from the central “pot”.
    (c) You just link to the central document if that works well for the variant.

  3. The names of all variants do not randomly begin with the characters “Fedora”, but they follow a common basis and common principles. Therefore, a cross-variant entry page is needed where these principles are explained and from where the different parts are referenced (and which contains a “getting started” section).

The demo page resp. a slightly alternative version for this new structure is a mockup, meant to let you get a feeling for the look and feel. It is definitely not the finished page. This is said at the beginning, but probably not clear enough.

Taking all this into account, existing differences turn out to be much smaller than they might appear on first reading. They are essentially ambiguities about single implementation details, which are present at the beginning of almost every new project and which have to be resolved in the course of an implementation.

2 Likes

Concerning this, my point was meant a bit different: having a central #Docs is not itself the problem in general, it makes sense for some tasks to have a central #Docs (as elaborated), but with reference to your argument above, the problem at this point is that there is no maintenance in most Docs that are managed by #Docs because no one is assigned. Everybody makes everything, so there is no responsibility at all: we cannot become aware if something gets orphaned. A member of #Docs has to be maintainer, not #Docs as a whole. Currently, there is no maintenance at all.

And we have to focus on maintaining what is really needed. People will not dedicate time to maintain something they don’t need. #Docs has become isolated, drifted away and doing activities that are not demanded, and the demand that exists is satisfied somewhere else (much improvised, and thus not always in a proper manner).

If pages become more a problem than a solution, they should be not presented to users. We know many cases that are orphaned for years, and how problematic it is what we present to users: we still do it intentionally… This makes any effort of the above untrusted as well and contributes to the isolation because the demand for trusted Docs has to be satisfied somewhere else, even if single pages would be maintained.

I also suggested to consolidate some efforts, but with an assigned maintainer - who maintains something for everyone who needs it (such as a beginner’s install guide). It is not relevant if this maintainer is part of #Docs or #marketing (in this example), as long as they have ties to both (and other stakeholder upstream+downstream): an open system. #Docs should be the place creating+providing the common framework/infra and it should provide a point of coordination and arranging/alignment. But first of all, this needs trust, and trust needs the absence of untrusted. The latter can only be achieved if we have maintainer for what we have online, and have offline for what we have no maintainer. Teaming up with others can also increase maintainer - if they get rewarded by doing this job in conjunction with us (this can be the case through what we can create+provide, but it will not happen if users don’t trust the outcome). Its a circle that can be positive or negative.

Hear, hear. :slightly_smiling_face: I almost think that exact paragraph should be placed directly in Fedora’s documentation. I think everybody sort of figures that out eventually anyway.

I think, that is an important topic for the future. To put it very exaggeratedly, at the moment we don’t need a maintainer because we don’t have anything to maintain (by docs). We need authors who create new things.

In detail, this is not entirely true, we would need a maintainer for Quick Docs.

The Installation Guide (and Administrator’s Guide) located on the Fedora page is not maintainable in this form. And never will be. It would also be superfluous, because there are already well-maintained installation guides for all variants - except Workstation. That is the weak point at the moment.

The “beginners installation guide” you miss so much can’t be a guide for Server, Silverblue, CoreOS etc. all in one guide. It already exists for those, and such a document would be a “mission impossible” regarding the content.

But we need (might need, see further down) such a guide for Workstation. And I guess it’s also Workstation, which is what all the questions in ask.fp.o are referring to. It would be a huge progress when you would conceptualize such a guide, and we could discuss it with Workstation WG. That guide would not be part of the above-mentioned Fedora page, but of Workstation box.

Creating such a guide is a huge task and takes some time. In this respect, it may be that, when the guide is ready, the guide is no longer needed, because Workstation has been replaced by Silverblue in the meantime. And there is already an installation guide for that. Silverblue is the new workstation. At least, that’s what a proposal currently being discussed for the next period of Fedora envisions.

2 Likes

Well, I’m not sure if I can agree to that. Obviously, a whole category such as Quick Docs would need more than one maintainer. So do the release Docs. It’s not just the Quick Docs. Be aware that these are linked to #Docs - and contribute to the bad reputation and trust.

Why create new things if we are not able to maintain what we have? Directly interpreted, I agree with you: but we do not need to author more content to increase Docs, but to replace old Docs that are obsolete at all. And then we need to ensure that things remain maintained. Generally spoken, and without insisting on “members assigned as maintainers”: these are complex social dynamics we have to facilitate because they do not yet exist (at least not in a sufficient manner).

Authors come when they trust and use Docs. If they don’t do both, why should they come to author? Or why should they expect others to use/trust?

Agreed :slight_smile:

… which is still our flagship. I agree that we do not need to do something on Silverblue or so, that was one of my points, so no objection about that.

Agreed. But we need to focus what is needed and do what we can. There is not just everything or nothing. The need is a workstation guide, especially for Beginners. There is one but it is maintained somewhere else and also no longer up to date. A server guide and CoreOS would be nice of course, but it ain’t that critical. I assume a server user will be able to get through the process somehow.

It will be based upon the distributed guide, which is roughly comparable in its approach to the 7-steps, as described above. I will compare Workstation and KDE, but I think the guide can cover both. It will focus the live images obviously. Only the maintenance of creating the boot media with Windows and Mac is something I cannot do.

Well, that makes indeed sense! Especially, in terms of separating a maintained install guide from the obsolete pages! Of course, our focus has to be clearly on the official Workstation, but it might be an idea to use a description below the “Workstation” title which indicates that it can be also used for KDE, and as far as possible, details both (at least in major things that are relevant for vast users). Much is transferable (as I said, I have not yet tested it, but I think the install guide can also cover both). Nevertheless, maintenance capabilities have to be kept in mind.

It is definitely the major part in ask.fp, followed by KDE spin (it cannot always be identified if something is Workstation or KDE). But we also have a large amount of Silverblue issues.

Well, I think this will still take some time until Silverblue will replace Workstation as major edition.

1 Like

While I understand the desire to increase security, which silverblue seemingly does, a corresponding increase in complexity and change to administration practices being forced on users with such a switch is disturbing to me. I have used fedora from the very beginning (and RedHat before) so am very familiar with the admin of workstation and the like.

I see many problems noted on ask.fp related to silverblue which is admittedly still relatively new, and as yet am not ready to even consider switching from workstation.

I would volunteer to assist with docs for workstation, noting that by its very nature silverblue would be difficult to fit into the current Rawhide → Beta → Current release with frequent updates – life cycle that easily fits Workstation.

@py0xc3 I would note that the link to the ‘7-step guide’ in your OP here seems broken.

1 Like

Fixed. There was a change in staging (the page has not yet been released).

Concerning a guide that focuses workstation (and KDE), I have started to draft a plan/approach; I was talking two days ago to mkolman from the Anaconda team, but not yet with marketing. I will create a discourse topic soon. For several reasons I think it makes sense to directly focus Web-UI and have a draft in the first half of the F37 lifecycle; the drafted plan/approach so far: py0xc3 / Fedora Anaconda WebUI Quick Install Guide · GitLab (supplement, after testing them, I think I will not make something for “Everything”/“netinst” images)

You are hired! :grinning:

I have taken it upon myself to create a plan for the conversion of the current home page and the Fedora page.

A first idea is to aim to go online with a very first version in about 3-4 weeks. It can not yet be complete, but it must already have a certain informative value and information content. Could you contribute a text for the Workstation box? Something like an overview (“How it works”) and probably 1 - 2 screenshots?

1 Like

Welcome to the club :slight_smile:

I don’t think such a switch will happen in the next 3 - 5 releases, if ever. In terms of downloads, Workstation has by far the largest share, followed by Server. I don’t remember the exact numbers right now, but it was something around 60 or 70% for Workstation. Unfortunately I don’t finde the exact numbers at the moment.

I suggest something introductive comparable to the first page of Silverblue or Kinoite plus some information about what is to come and when? I think this should be no problem.

Related to the planned approach for the Guide I will create, my suggestion is to center the category around Workstation but also consider KDE as major spin. So focus the structure on the problems and not the edition/spin, and note within pages that it, e.g., also applies to KDE or add a section about the difference in KDE (like a commit: this is the solution for workstation → for KDE, + this and - this, or something like that). That considers the audience and their reasoning as we know it from ask.fp, and is usable for advanced users as well. Having an additional advanced category that only works with pointers to pages/sections might be worth to be discussed as well.

But when elaborating, I think we should create a new thread for this and just relate it to here or such.

“We all know that “lazy approval”-based “rough consensus” and interpreting every response “the most positive way” are major institutions”

Yes they are and not just in Fedora Docs as you point out. These practices are found in other Fedora groups and are widely used in the world.

1 Like

I feel your pain! What I have always had an issue with in the doc’s isn’t the centralized nature so much, but more that whenever in release cycles (ie version) the particular documentation is introduced, it is forever tied to the specific version with the established procedures. This is meant for the parts of Fedora Linux that become core, such as NetworkManager for example. Doing a search from DuckDuckGo yields the Wiki first choice and as you can see here Tools/NetworkManager - Fedora Project Wiki, it is referencing FC17! I feel it is more intuitive to have the topic of the doc be versionless unless it is specifically a version pertinent item. But if you go through the official start page doc link you get the newer versions of our docs, just the details you need about NM are tied to the older docs/wiki.

2 Likes

Sorry, I didn’t saw that there had been further developments here.

Well, I have to be honest. I don’t understand this argument. If you argue that this is a more widespread problem, I would say that none of these institutions are problematic on themselves. It is the organizational and institutional architecture (and the contained flows and interactions) in which these institutions are embedded that makes them a complement or a problem. But in here, I just focused on Fedora Docs within Fedora :wink:

Well, it is not really a pain. I just see that underlying problems remain hidden, due to reciprocal false assumptions that make symptoms look like origins. I am not questioning the centralization in general, but our current implementation in the given organizational and institutional framework.

My goal with this topic was to encourage people to question what used to be taken for granted, to replace maybe some false assumptions, and especially, to practice some self-reflection. A “hard counter perspective” might facilitate this - or just create a slight cognitive dissonance that might result in a little broadened horizon, and maybe encourage people to compare here and there what type of Docs (or other things) work and what not, and maybe question why :slight_smile:

The current release notes issue could be seen as another example of symptoms but one that does not come from within but from outside, so vice versa to most of my examples. So I don’t argue the Docs team is the problem or so (just to avoid a misunderstanding).

Sooooo, I have read this several times and I am still trying to really understand it.

It seems like the crux of your complaint is something to do with “planned economy” vs some kind of … I guess … laissez-faire hand-of-the-market solution? I’m having trouble connecting that into all of the rest, other than that it has somehow instilled some kind of distrust.

But this doesn’t seem to me to actually connect to the install guide problem you highlight, or to the more general one of keeping documentation up to date. Maybe I’m missing something, but it feels like you’re making a leap from what you’re presenting as the root problem to the actual example problems.

Can you help me understand what I’m missing?

In the meantime, let me offer a counter suggestion. I think the concrete problems of obsolete documentation with unclear maintenance come from these things:

  1. Simply not having a functioning docs team for a long time. That’s a big hole to dig out of.
  2. Many developers, sysadmins, packagers, etc., do not have a natural habit for documentation, and with people volunteering their time, we don’t have a forcing function for participation.
  3. We don’t have as many non-engineers as we really should. (And technical writing is really a particular skill!)

There are some other things — like, limitations of Antora and our use of it; the fact that we haven’t made a “centralized” decision to pull the plug on the wiki; git-based flow (whether with pagure or gitlab) suits a particular mindset; etc. — but I think the above are really key. And I’m having a really hard time seeing how our decision-making process is the root cause here.

3 Likes

Well, my major goal was what I noted in my previous post (the last part of #14), so it was less intended as complaint and did not intend any explicit action.

Absolutely. But “why”? It’s a bit a vicious circle, because the absence of trustworthy Docs is one of the reasons why people do not use or get into the Docs, and therefore, why they don’t think of contributing. Keeping sophisticated Docs with much elaboration of anything, and assuming this approach is supported by WGs/SIGs/users by lazy approvals (since there was no objection) and that at some point, this will have sufficient contributors to maintain all that, contributed to the problem. A lot of time was invested with such assumptions. And it remained unquestioned (from all sides). But trustworthy, maintained content (satisfying the demand of people) comes before wider volunteering of people. It has not worked the other way around - but the assumption survived long.

On the other hand, people from other stakeholder groups assumed there will be a Docs team that does the job, which frees them from contributing to Docs. A question is if other teams/SIG/WG even considered themselves to be addressed when Docs ideas were put forward that were related to them (ideas that maybe have gone along with hopes for increased contribution if (lazy) “approved”). So, in the end, reciprocal unquestioned assumptions removed interactions and collaboration.

Well, agreed. This is a general issue but we also indirectly educated people that way: Docs are needed, but there will be a Docs team to do it; the same reciprocal assumptions noted above. There used to be no awareness of the respective other condition, just unquestioned habits & unrealistic assumptions. However, it is important to stop avoiding discussions about issues whose necessities we might not like: if we need Docs at a very place, we have to enforce them, and collaboratively think of how. If we do not need them at a very place, we have to accept the fact and do not provide what we cannot. The capabilities of the Docs team itself will remain limited.

I hope that makes my previous points a bit clearer. I already recognized that some things were interpreted other that I meant it (at this point, I am the origin of the problem :).

However, my previous arguments are no longer fully up to date: ironically, in the recent discussions, I have seen a lot of developments (this is at least my perception). I have never been involved in the release notes, but the developments/decisions in this and other areas face the reality about what we can do, and who else has therefore to also do something, where we might get rid of something and where discussions have to take place with another group (that is maybe unaware and in the same situation like the Docs team). The same for the risen discussion about separated/dedicated Docs for Workstation, where the absence of interaction with the WG (I think this “assumed responsibility” evolved before my time) was also already a point discussed without presumptions, in order to think of what to do about it and with whom to talk. However, with the new approach (if it becomes accepted), I think we can fill the role ourselves for the “Workstation & spins” Docs and release the Workstation WG from “forwarding” tasks. Working with affected teams directly is more efficient imho. But anyway, becoming aware is a major step in solving problems & finding alternatives that work, and also to find out what the issue was and how to avoid it in future (and to facilitate collaboration).

I don’t know if my topic here had provided any incentive or triggered some reflection, or if it was simply the survey that created a rethinking (although I think the outcome was anticipated by most of us), or if it was just a coincident. But the recent discussions, including some decisions, around Docs implement many points I meant.

A remaining thing is maybe that we keep things online until we have replacement, even if something is “broken” and undermines trustworthiness as a whole (facilitating the outcome of the survey). The install guide was meant as a “worst case” example. We already agreed that “repairing” this does not make any sense. However, separating new Docs is already a way to prevent the bad reputation of the old to be transferred to the new, which we have seen to be successful already at Silverblue.

So the issue I still consider open at the moment is only ensuring the maintenance of the new Workstation & spins Docs. But this discussion/topic has just begun and does not belong here. Beyond that: just keep in mind that “no objection” does not imply collaboration, confirmation, or takeover of responsibility. Sometimes we have to be not “lazy” and actively start talking with each other :smiley:

Essay end :wink:

I think, it is at least mixed. CoreOS, Silverblue, IoT, Server had their own documentation far before the docs team came up with the variant-oriented plan. And Cloud WG, which currently shines through non-participation, also has (or rather had) their own documentation, albeit circa 2016. However, your argument may be true for Workstation WG.

Thanks, that helps me understand better. I want to address one thing, here:

It’s possible that this just is not translating very well. “Lazy consensus” is kind of a tongue-in-cheek thing, and actually is meant to encourage the just getting things done. The rule is: if you think you can make something better, tell people your idea, and then get to work without waiting for some kind of big official ruling or stamp of approval.

2 Likes

Sorry :smiley: Yes, that’s a translation issue. I should avoid translating puns, that’s never a good idea I guess. The meaning should be that the lazy approval/consensus serves us well, but like every institution, it can have situational negative side effects that we need to keep in mind to balance them.