Workstation & Spins Guide: how to solve the issues around this guide by adjusting the approach

Project Discussion
1

The conditions around the “Workstation & Spins” guide have changed a bit. Especially my own contribution will in future be limited to finalizing the Web-UI installation guide before Web-UI’s release & processing merge requests or tickets related to the Workstation & Spins guide (including the Web-UI guide). I also can maintain the major pages of this guide in terms of checking and setting outdated/false content offline if we agree on such an approach. Unfortunately, my workload in other areas has strongly increased.

Therefore, we have to adjust the approach to have something that on one hand can be published without the risk of providing misinformation, and on the other hand, also adds value for the users even without much content from our side. The problems of this guide and more generally guides around workstation & spins go beyond its boundaries. Or in short: there is a reason why we have not yet such a guide for our major edition. So the issues are “overarching”.

The draft for the new approach is pushed to staging (wait an hour after this post): https://docs.stg.fedoraproject.org/en-US/fedora-workstation-and-spins/

What does this change tackle and thus, what does it contain?

Issue 1:

Our “good first issues” on gitlab are not worth much. The target audience of this guide is rarely used to work with and on gitlab. Even if they use the guide, they are unlikely to checkout the gitlab board. However, the target audience (such as the people on ask.fp) is often not very “secure” around the institutions of Fedora and Linux in general: people avoid to engage or actively approach others if they are unsure what is expected from them and what they have to expect in response. The latter problem fosters the first, and it also fosters that the audience will seldomly end up at “how to get involved”-type pages.

However, on ask.fp, I experienced that if we let average users know about specific tasks they can do to contribute at the places we are in contact with them, especially if these tasks are related to their needs, there is a large interest to contribute. E.g., this is how we could effectively contribute to tackle the asus_ec_sensors bug in the kernel.

How to tackle issue 1 & exploit the described tendency towards collaboration:

Formatting, language improvements and comparable activities can take a lot of time in authoring Docs. But most users can do that. On the other hand, I’m quite sure most of our audience does not feel sufficiently secure to author the technical content themselves. So, in order to give an incentive what they can contribute at a place they are likely to find it, I have added the first two pages of the new install guide, which are drafts for the future Web-UI guide (these two pages are not Web-UI specific and are a type of independent “getting started” that fulfills its purpose already now). To make clear about the issue, I have added a clear CAUTION box in the beginning:

This page is maintained and its content is kept up to date. But it is considered as draft because there is still work to be done: formatting and language improvements. Feel free to contribute! You do not need to pick up any responsibility or maintenance! If you additionally want to split the page, open a ticket!

Imho, we owe the users to maintain content to ensure that nothing contained undermines their problem solving and that everything is correct and sufficiently up to date. However, having content that is not perfectly formatted cannot undermine their problem solving, and most important: it tells them exactly where they can contribute and with what! And they know in advance what is expected from them, and what they can expect.

If this works out, experienced technical authors can very effectively team up with average users who are on these pages later (content still fosters SEO, even if not perfectly formatted). This saves time for technical contributions and already adds value for the users from the beginning.

Examples: Why Fedora Linux? , Which Fedora edition, spin, or lab to download? , How to create an installation media?
→ Btw, @pboy , I already implemented your proposal for splitting the pages. You made a very good point about that. I also split some paragraphs as you suggested.

Issue 2:

The “current Docs” for “Workstation & Spins” are in fact ask.Fedora - this is what currently incorporates that role (whereas experienced users go upstream or know how to interpret and where to apply Quick Docs). Demand has clearly shown that. My interpretation from feedbacks is that there is a “traditional Docs” demand for everything up to the installed Fedora. But in other cases, the stable “constant” is ask.fp, which has proven to satisfy most of the demand of users.

I think in this respect, even if it hurts, we should not try to tackle that or to compete, and always keep in mind that Docs shall serve the users, not vice versa. If it suits the users, why try to change that: ask.fp and Docs have the same interest. So, we should avoid to compete but think on how we can identify and fill the gaps, to complement the users’ problem solving (one issue at ask.fp is that there are often more cases than available supporters can tackle, whereas on the other hand, a lot of time is wasted to tell the users what information we need to help).

How to tackle issue 2 & exploit incentives and common ground:

The guide is already from the beginning problem-oriented. However, creating many more pages is at the moment not feasible. The above approach can facilitate more over time if it works out, but I question if it will ever cover everything that would make it a “full scale guide”. Advanced users go upstream or know how to interpret Quick Guide pages (including what is up to date and what is only indicative), non-advanced users on the other hand depend on ask.fp: identify what is the upstream for a specific problem is a skill! Interpreting upstream if not intended for beginners, such as systemd, can be a skill, too!

Yet, given ask.fp’s structure, it remains hidden for many problem-oriented search queries on search engines. Further, especially less experienced users often provide not the type of information that is necessary for problem solving when opening an ask.fp ticket: this takes time from both them and supporters.

However, we can create a “catchment basin” so that users can arrive at our guide. Over time, we can increase the number of pages around problems that we can tackle directly without forwarding users to ask.fp. However, if we cannot tackle a problem, we can still create pages that let the users know about both ask.fp but also which information to provide when opening an ask.fp ticket to reduce the amount of time and posts necessary from both users and supporters → Examples: Installing Fedora & post installation , Issues around Update, upgrade & package/software management

The strong & successive alignment avoids competition with ask.fp, follows the demand we know, and maybe facilitates cooperation. I saw that our changed approach in general already facilitated some some merge requests from ask.fp seniors and others, which I really appreciate! Maybe a stronger alignment can increase that. If we additionally also fulfill indirectly (but of course not only) the role of a squid, this might also facilitate that average users start to contribute more (if complemented by the above two issue approaches).

A slight note: I mean “problem solving” in a generic way, so how people process issues & get their goal implemented, not only with regards to problems on ask.fp.

I have already adjusted the index page to incorporate the approach. Yet, I think the index page needs another revision before publishing (I had to be a bit rough yesterday). However, I think the index is already understandable.

I hope that makes sense! If anything is not comprehensible or so, let me know so that I can elaborate. Of course there is not just the “take it as it is or leave it” possibility, any idea for adjustments will be appreciated!

So, what do you think of that approach for the beginning? It is something that can be published, might facilitate contribution & collaboration (at two places), but also adds value itself from the beginning and actively helps users to solve issues/problems or to get their Fedora customized the way they want it. And we have something contained that creates incentives and can develop over time, without having obsolete content that has become misinformation (which, at the worst, can hinder the problem solving).

1 Like
2

Some basic points and a solution proposal

  1. I consider Workstations docs and ask-fpo as complementary and not as alternatives or 2 different approaches. Ask-fpo is problem-oriented, interactive, oriented to individual cases. Docs is systematic, you read alone, and is oriented to overview and overall view. Both are needed.

  2. Workstation is the edition with the highest download rate. On a Docs page, we can’t just leave that out. And ask-fpo is in no way a substitute that can make a doc superfluous. It’s bad enough when we have to omit Cloud. But this is after all a now just new edition.

  3. What we can manage depends on our resources. We can’t do magic, but doing nothing is not an alternative either. So we have to pragmatically find a solution that has an information value > 0, but that is unfortunately far below 100 to begin with.

  4. Where there is nothing, nothing can grow. So let’s start with a small solution and then work on expanding it step by step. This is tedious and may take a long time, but in the end it works (almost) always.
    And if that doesn’t get us anywhere, then we’ll just stick with what we have.

So as a compromise, let’s start with a (short) “Getting Started” guide, and after release 37 try to get more articles on it via blog, calls on ask-fpo, Fedora Magazine and others.

And if that doesn’t get us anywhere, then we’ll just stick with Getting Started.

And if we find in 2 or 3 years we can’t even manage that minimalistic approach, then we can kill Workstation on docs pages. But not at the moment.

3 Likes
3

I didn’t say something else :wink:

That was one of the points. The traditional approach does neither add value nor give incentives to people or indications about expectations. Generic pages have already proven to not work or facilitate contribution. To tackle that, the proposed pages are intended to contain already something that can grow.

I’m not sure if adding another redundancy is a good thing. Why should a user go to a technical Docs, go to the Workstation/Spins box, to get this type of information. This is already provided on at least two other pages, which are more reasonable to click for that. Especially the major Fedora page will contain and link to more related information, being most suitable for generic overviews and such. The points for a Workstation/Spins ‘getting started’ you elaborated in the other topic are widely contained in the “Fedora Linux” box.

Imho, the problem is less that it does not add value. But that it “captures” the search engine rankings of other pages which are intended to provide this information. On one hand, it “competes” on search engines with our own “Fedora Linux” box, and on the other hand, it competes with the major Fedora page about hits/clicks. I guess the other two pages are more the target for users formulating corresponding queries. So, we change the rules from “Docs serves users” to “get users to justify a Docs box” a bit.

I understand your doubts about my approach, and they are reasonable! But with regards to my last argument, we should ensure to provide value and not justify boxes.

So, if we go a “traditional way”, we should get rid of a box that does itself not provide value but only competes with other sources. So, in this case, let the Silverblue and Kinoite editions have their separated boxes, since they really provide value for many users. At the same time, merge Workstation with Fedora Linux.

With regards to the above: because Workstation is the major edition, it can make sense to merge it with our “major box” (“Fedora Linux”) and indicate that in the description. This box already contains a general “getting started”, and general guidance applicable to Workstation. So, major box for the major edition :smiley: Just create a box because it is the major edition is imho not sufficient: we cannot fill it. This is more a discussion for the Workstation WG. Only they can create and maintain a full scale Workstation guide.

CUT :smiley:

I guess it does not make sense to go deeper in this discussion. And since we want to provide something for the users, I guess it makes sense to involve them.

What do you think of simply making a poll?

I see currently three suggested approaches (plus the usual “something else”):
→ implement the approach of this topic
→ limit the workstation & spins guide for now to a “getting started” section like that of the “Fedora Linux” box
→ get rid of the separated “Workstation & Spins” box, integrate it into the “Fedora Linux” box and leave the freed box to Silverblue & Kinoite
→ something else (users can write comments)

In the end, both of us are guessing. We have no proven data. So I think a poll is the best way to involve the audience, or at least many of them.

If we announce polls on ask.fp, this usually also leads many average users to participate as we have seen in past polls.

Nothing fosters contribution more than inclusion.

Does that make sense?

4

I don’t think that ask fedora should be considered an alternative to documentation.

At the very least there should be some documentation tied to workstation. The amount, substance and topics for that documentation is certainly something the docs team should consider but I think not having any documentation for workstation would be very strange.

As it relates to the linked page for review, I am not really sure I understand who the audience is or what it is supposed to inform that audience of. It isn’t very understandable in it’s current format.

2 Likes
5

Its more about the real world condition/practice, not consideration. Ask.fp has taken over the role for people who could have used a Docs instead - because there is no real Workstation Docs that can be used to solve problems or to customize a system the way a user wants it.

The problem is that there is no one to author it. The Workstation WG does not contribute to guides. So having the box means that we have at the best another getting started like that already contained in the Fedora Linux box or what will be on the future Fedora website.

So generally, there is a consensus that your argument is right. But there is no one to author the guide.

Be aware, a Workstation box does not yet exist - this is at the moment part of “Fedora Linux”. Having a dedicated box is a “new thing” which is not yet introduced. So, if we talk of getting rid of it, we mean getting rid of it in the testing stage before anything has become introduced. I originally created it to facilitate a new problem-oriented approach separated from the traditional approaches, but I remain on my own and unfortunately, I have to decrease my workload due to other obligations.

The major content this guide was intended for is the Web-UI install guide, which will be released in some of the future Fedora releases, but this will take time (it is not even decided which release). The original reasons for separating it from “Fedora Linux” have been resolved. So what I have authored so far, cannot be published atm anyway.

I guess the possibility of a Workstation guide that has technical Docs content does not exist atm. You have to go upstream.

Advanced users go upstream and do not need a dedicated Fedora Docs. For many, the possibility to go upstream is a major reason for using Fedora at all. This is likely the reason why there is no noteworthy contribution from them to a Workstation guide. So, the audience is people who do not know how to identify the relevant upstream for their problem, and even if they can identify it, how to interpret content of upstream Docs that are sometimes intended only for experienced users. In short: the audience is the average ask.fp member :wink:

Maybe the examples in the initial post illustrate it best.

6

When I was asking about the audience, I was talking about this document: https://docs.stg.fedoraproject.org/en-US/fedora-workstation-and-spins/

If the intended audience for that document is the average ask fedora user, it probably isn’t consumable in it’s current form.

I have read it twice and I still don’t understand what the point of it is or what it is trying to tell me. For me, it isn’t even understandable enough that I can provide constructive criticism on how to make it better.

7

Ah, yeah. As I said initially, the index needs definitely another revision before publishing. Especially removing some parts of the recent approach. Since it will take time until we have the web UI introduced, I guess it also makes sense to remove this for now.

8

Which 2 other pages do you think of? I’m not aware of any.

The core Fedora Linux Box contains nothing specific to Workstation.

The Workstation Box Getting started would describe how to master the installation screen (Anaconda) for Workstation. And that would be valuable information.

Please, remember the concept of the new documentation: variant-orientated docs!
The ‘Linux box’ is strictly Edition overarching. It doesn’t contain anything specific to Workstation, and it should definitely not. There is no information e.g. how to master the Anaconda installation screen, no advice what to choose from the alternatives, etc.

Yet another poll might be nice, but it won’t bring a solution and especially not a long-term sustainable solution. A poll provides a non-binding snapshot, nothing more. And we already have a poll that Anushka has conducted. And that gives us good indications. In the end, we have to make the decision and then realize it.

2 Likes
9

When it is about the generic information as outlined in the other topic, it is widely equal to the Fedora Linux box and the future Fedora webpage.

However, as you are now talking about a factual Workstation-specific install guide: of course, if we had that, this would be a good thing! However, you have to take this responsibility because I will only have time for the WebUI guide. And it might be noted that it will contain some efforts: “capturing” people to superficial or sparse guides was a clear and explicit criticism we received. So, casually speaking, we should avoid something that only tells the user when to click “next” or so.

So far, no one has volunteered to create a new install guide for the current anaconda. That was and is the problem.

Everything we have so far has orphaned and developed towards a mixture of different releases and it is in noteworthy parts drawn from Fedora 21. So, I suggest to stick with the maintenance concept to avoid orphaning and mixing to happen again. Another suggestion would be to not use the collected old content: revising and reviewing this old mix will possibly take more time than writing something new, and it would be also vulnerable to accidentally keep something obsolete. The screenshots cannot be re-used anyway.

You can use the two initial pages for the WebUI if you want (they are not WebUI-specific). There is formatting and such to be done but at least the content is up to date.

I think that might be shifted to tomorrow. It is indirectly related to my point. I guess my point on the agenda does not take much time, so no worries :wink:

10

FYI, I saw this (and also, @pboy, the message about docs you sent me…) I just haven’t had time to really read throughly and process in order to provide opinions. Which I have some of, but need to set aside some time. :classic_smiley:

11

If that is the case, we could pilot-test Vale linter to the writing workflow. I haven’t done it before, so if there are people who are familiar with such automation, I’m happy to formulate planning and reach a consensus to test Vale.

1 Like
12

I think pboy’s approach to get clarity makes most sense atm: To drop or not to drop Fedora Workstation Edition from the Fedora documentation pages - Fedora Discussion

So I think it makes sense to consider this topic closed.

13

Hey folks, this was on my to-do list to read through and catch up. I have some perhaps naïve questions that I have threaded below.

I was really surprised by this one. Is there any particular reason that the Workstation WG is not involved with any documentation? Was anyone from the WG engaged or asked about this before, or have they turned down an interest in docs?

This feels like a red flag to me—given that the Workstation WG is doing heavy lifting as main stakeholders of the Edition itself, they should ideally be involved as a leading voice in how the documentation takes shape. I am trying to better understand if there is a reason or barrier that this is not happening today, or if there is something deeper here.

I was wondering, is there any data to support this? I am curious to know how we know this.

1 Like
14

There is no particular reason I know of. Workstation WG simply didn’t join the discussion we started around April this year about improvement of Fedora documentation.

Have look at Issue #340: Do we want to have Workstation User Documentation from F37 on up. - fedora-workstation - Pagure.io. The currently voiced opinion is

“A getting started guide for Workstation, which is intended for non-technical users who just want a desktop, doesn’t make much sense to me. The format is wrong. The content generally isn’t needed.” (aday)

“Workstation is different: you shouldn’t need technical documentation in order to get started. For example, you shouldn’t need to know about the package manager or the command line.” (aday)

So, if we don’t get a different feedback, the consensus of all “stack holders” is not to include Workstation in Fedora User Documentation F37 and up.

I don’t know, and I’m wondering, too. Everywhere I read about several distributions, I notice complaints about Fedora’s missing / incomplete user documentation, which makes it usable for engineers but not for everybody else. And Fedora is discouraged for “normal” users. But maybe I’m biased and deceived by selective perception.

2 Likes
15

I know this isn’t your perspective that is being represented here but it makes no sense to me.

When someone new first installs Fedora workstation, if they don’t have prior Linux experience, they are going to have no idea what to do without some basic documentation. It doesn’t have to be some deeply technical guidebook but it needs to explain the basics.

16

With regards to the ticket pboy has opened, Allan’s immediate focus on upstream Docs resembles what is in my perception usual in “technical channels” of our community.

A general implicit indication:

ASSUMPTION 1: there are many advanced users with Fedora, and you will find many of them in our mailing lists, in technical WG/SIG tickets or their preferred communication media, many on conferences, and so on: they are interconnected, collaborating and exchange knowledge to solve problems. They use the social and technical Fedora infrastructure for that, or infra that is practically linked to our community (e.g., gitlab).
ASSUMPTION 2: there are no users that are so super advanced so that they need no type of Docs for any type of tasks.
ASSUMPTION 3: What I indirectly implied for “advanced users” is to be sufficiently contained in the Fedora community and able to make use of the devel mailing list and such: I assume an advanced user would prefer to write something in the devel mailing list or at least on discussion.fp before grumbling on external media.

Questions:

  • how often do they need/exchange/mention/refer to Docs-type information?
    • how often is it our Fedora Docs?
    • How often upstream?
  • With regards to the argument that there are simply no Docs from us they could refer to:
    • how often are there complaints from, e.g., the devel mailing list, technical WG/SIGs, …, about it? And why? If there is a demand, why don’t they lobby for it? Escalating information is quite easy in our community.
  • Why is there no/minimal contribution from advanced users when it comes to author Fedora Docs if they have a demand for that? I mean, people contribute a lot for this community! Why not here?

Complementary fact: Fedora-related people do author much Docs! But you will find their contributions mostly upstream: dnf.readthedocs.org , anaconda-installer.readthedocs.io , systemd , … (obviously this also leads to the blurred definition of when someone belongs to Fedora and in which context). Also, I do not know explicitly, but I guess that Fedora-people-related contributions can be also found in btrfs.readthedocs.io and https://docs.kernel.org/ :smiley: These are btw all Docs I had been referred to from within our community over time.

Important fact to have in mind: arguments like “I think we need own Docs” do not imply real demand but only opinions about perceived demand (be aware that I just want to make aware of the underlying fact! I do not say that such arguments are wrong or so!). Of course it is the same vice versa. However, the absence of contribution could be slightly more indicative: those who could author it, largely do not. Why?

I have also heard the upstream-argument sometimes explicitly when it is about writing Docs: “why? go upstream”. What I have still in mind is the FROSCON, where I heard the argument many times. People who are deeply into Linux have sometimes no understanding for the need of Docs in Fedora. However, conference experiences are subjective by nature of course and not necessarily universal.

Nevertheless, obviously, what “advanced” technically implies remains a matter of definition, and if we engage in this, we might need to define “advanced” a bit more precisely. E.g., by actions?
“choose proper checksum algorithm in btrfs to be efficient on 64 bit”, “use xchacha20 because there is no AES-NI on the machine”, “rebuild rpm because I have a related error with dnf”, something like that?

However, based upon these thoughts, in the beginning this “Workstation & Spins” and “Web-UI” guide project I defined “advanced” more or less as users who are able and satisfied by upstream Docs and thus, not the audience of the (originally intended) Workstation & Spins guide. So we have to be careful to not end up in tautologies :slight_smile:

Concerning knowing: we have to be clear that our community structure makes it hard to evaluate things like that “for sure”. In fact, we do not even know for sure that the big survey we conducted about the Docs is representative. In nearly any debate we have, the vast majority that is affected is not involved (we cannot even identify it definitely as such). So from that point of view, my assumptions are closer to a guess than to scientific evidence :wink:

That’s the point :slight_smile:

normal != advanced

17

I agree that in case of doubt, getting rid of the box is the best solution. I would definitely favor that over the compromises elaborated (including my one of the beginning of this topic) since it became clear that the guide cannot be fully build up and maintained so soon (if at all).

But what he suggests is closer to what we have originally planned than any compromise proposed since. It brings the relevant knowledge/references together so that the skill of identifying upstream Docs is no longer so critical. And having it together with reasonable terms/names that users might read when experiencing an issue might also facilitate problem solutions. That can already help some users, and it is something that can be developed. Don’t you think?

The efforts to add “TIP” or “NOTE” boxes or so here and there for beginners should be limited, and can make also a difference with minimal efforts. The outcome of that would be close to the approach we originally planned, but not for beginners with advanced boxes but for advanced with beginner boxes. He didn’t say something about it explicitly, but I guess they will not resist to that. At least, it can be talked about it.

I agree with you that an “up to the installed Fedora” guide at the center would have been nice, and could remain a goal on the long term. But it is not everything, and also, when we planned that, we didn’t consider that the new Fedora website improves their guidance for beginners.

We have now the Workstation WG involved, this is already worth much, and we can combine it later with the “up to the installed Fedora” guide once WebUI is released. I think step by step is better than nothing, don’t you? Just some thoughts :wink:

Sorry to ask, but is your argument referring to me? If so, I do not understand what of my arguments you want to tackle :wink: If it is related to the original debate from above, I think it has shifted to the ticket with some arguments being in here. Most of the arguments above are obsolete!

18

No, not this time. :wink:

It is related to the summary opinions in @pboy’s post which I assume came from the pagure issue.

19

This is interesting. I think it was the right decision to open up that conversation with the Workstation WG on Pagure. They also need to be a stakeholder of their own documentation. I have a half-finished comment to add there soon.

If I could make a wish, it would be that the Fedora Docs Team shifts more into a role of facilitators of documentation across the Project, and the burden of having to describe, define, and document the bajillion different parts of Fedora is better shared with other teams.

To add a perspective, this is a hard challenge that is not exclusive to Fedora. Many communities struggle with this. But it might be more noticeable in Fedora, because people who work in Fedora often work in other upstream or downstream communities. It is a hard challenge!

This is insightful to me. There are definitely several documentation projects inside and outside of Fedora that have relevance to something like Fedora Workstation. For example, we have the Fedora Developer Portal on top of everything else that was already shared here! :smiley:

But, this leads me to wonder…

I would hypothesize that there is an expectation for Fedora to have docs because it is a huge entrypoint for people who are consuming the different projects and technology that are available in Fedora. You don’t install dnf into a Python web development project, you use dnf because it is a tool available in your distribution. You don’t install systemd into macOS, you use it because it is a service available in your distribution.

With that hypothesize in mind, what do you think about the idea of Workstation & Spin docs being a jumping-off point instead of being a source for other information? Instead of owning the work to create new content about these tools, what if we became more of a place for integration of different projects and documentations? For example, if you use Fedora Workstation, then you don’t turn to Fedora Docs for content about a tool or system service, but instead it is a place to find what it is that you are looking to do in greater detail? To me, an approach like this for Docs would better model the approach we take at the distro level of being an integration bed for several different upstreams.

Does that make any sense?

20

100% agreed