Boxes on the Fedora Docs page

Answered here: New Documentation Homepage needs review and help - #15 by siosm - Fedora Discussion

I think it should be possible to avoid groupings, and make Silverblue and Kinoite independent boxes.

I would say we can put the Labs as one of the little boxes as they are a minor thing, then we have another big box for separating Silverblue and Kinoite. Also, I guess the Labs box will remain widely a description of Labs in general with a link to the labs. So that ain’t much important.

If we can have only four little boxes, we might replace “Fedora Tools” with the Labs? I’m not sure if we need the “tools” page. If at all, tools should be a sub-page of “Fedora Linux” or the respective editions’ boxes, doesn’t it? How to use the tools on Fedora is already partly incorporated in other boxes (e.g., “Fedora Linux” box → update with dnf). If people seek dedicated guidance for dnf, they end up at dnf.readthedocs.org . The same for anaconda and such.

So, make Silverblue and Kinoite separated big boxes, put Labs from a big box to a little one, and remove “Fedora Tools” as separated Docs page (maybe make it a sub-page in the “Fedora Linux” box or so). Does that make sense?


Aligning with the new website is a good thing! The problem with Workstation and Spins is that these Docs are written, atm, by 1 person. The workstation WG / kde SIG do not contribute at this point. So even the “common WS+KDE guide” will be widely minimalistic. Therefore, it can look a bit pathetic to have that at the first box or so. At the moment, it contains the index page elaborating the idea and approach of the guide, it will have a page about backups, snapshots, automation to illustrate, and I will create an install guide for it (but for Web-UI only!). In the next half year, I will not have time to maintain much more.

So we will have to see how far the new approach facilitates more contribution than the recent approaches. Then we can see if we really can make it to get a “full scale dedicated guide” for Workstation (and spins).

Additionally:

Please do NOT answer there but here :wink:

Unfortunately, currently not. We might be in a better position when the Cloud (to be) Edition provides a documentation we can include.

But we can remove the link to the Emerging-Fedora-Desktop box and replace it by direct links to Silverblue and Kinoite (with a different description text, as we had previously).

Please, remember our discussion about the page structure, among others with Anushka. The boxes are not a dice game. :slight_smile: In the middle part we have Fedora deliverables (product we are not allowed to say) that are immediately usable. In the bottom row there are various meta-information and at the top there is an overview part.

No, it doesn’t! You are just accidentally throwing the entire concept of the documentation, which we’ve discussed at length, out the window. That really doesn’t seem like a good idea to me. Solid documentation is not just throwing together a loose-leaf collection at random.

At that time, I was not contained in most related discussions as I had to focus other things. So in some cases around that topic, I have only abstract information. So in this respect, you have to be indulgent with me :wink:

I’m not sure if I fully get the point. I do not see deliverables or immediately usable information in “Fedora Tools” and Labs, as the related information is inevitably maintained somewhere else, we can only note that they exist.

However, I think I got your point about the big boxes: you mean that the big boxes are to have all editions and such covered, to have an overview of “existing Fedoras”. From this perspective I understand that it makes sense to have the Labs contained in a big box, even if it only makes aware of their existence. I still struggle to see the sense of “Fedora Tools” but since I now understand why you do not want to shift “Fedora Labs” down to the small boxes, I have no problem with keeping them where they are.

With this in mind, it might be worth to focus on your other point:

I elaborated something about this possibility at the end of my last post above (so, the part at the bottom, which I cited from the other thread). I think I edited that part after you wrote your answer.

OK, this is indeed a valid point. I had not realized how little Workstation docs we had.

Another thing is that Kinoite and Silverblue docs are 95% the same. We could unify them too.

Sorry, bad choice of words. I did not want to mean that this was intentional or malice. Just unfortunate.

For the KDE Spin, we intentionally don’t want to maintain docs. The documentation should be either about KDE and thus upstream KDE docs or about installation and that is a Fedora general topic, not specific to the KDE Spin.

What we could also do is to unify the Silverblue & Kinoite docs and then make one box with the “Fedora Silverblue & Fedora Kinoite” title and “Documentation for emerging desktops” or something as description.

The problem-oriented pages I will provide focus upstream to focus sophisticated information without enforcing that we have to maintain everything. This is something Docs have neglected too long: Fedora can make use mostly natively on upstream Docs.

But at this point, we just want to give a point to start because not every user knows about when to go where (or to identify what tool/package is the origin of a problem). E.g., in the problem-oriented approach, we focus a problem a user might experience based upon the information the user has (“the questioning or reasoning of the user in this situation”), and provide the point to start where the user is likely to seek it (our Docs): then, provide what is immediately related to Fedora (or too complicated upstream) and provide upstream links where possible. In short, we link the problem as it appears on Fedora to the related upstream Docs. Also, sometimes a problem that becomes revealed “on KDE” can be caused and related to Fedora. Interpreting this needs some knowledge in advance. If such a problem is widespread, we should provide something.

So, for some users, assuming they know when to go where upstream and assume they know how to interpret some more sophisticated upstream pages is not sufficient. This is an example: modules/ROOT/pages/BackUp.adoc · main · fedora / Fedora Docs / Fedora Linux Documentation / Fedora Linux Workstation and Spins User Guide · GitLab
→ e.g., “Automate regular BackUps/snapshots” section, we have upstream Docs because they can be transferred to Fedora and indicative for everyone (especially advanced users), but also an example for users who are unable to interpret upstream, so that they can adjust the example (the page is not yet final).

The problems I wanted to tackle are a bit inspired by what I see in ask.Fedora.

Anyway, I do not see a problem to integrate this approach into the “Fedora Linux” box, so get rid of the Workstation&Spins box as proposed as alternative by pboy and me above: most problem cases I have to deliver are experienced by desktop users of Workstation & KDE (because these are most widespread among average users), but the problems are nevertheless not specific to these editions/spins.

So, I am open to talk about integrating these into the major “Fedora Linux” box, which at the current stage, can make sense, as alternative to merging Silverblue+Kinoite. I am not convinced that the new Workstation+KDE approach will end up as a “separated full scale guide” that keeps reliably maintained, it was a compromise to balance an issue in the old “Fedora Linux release” box, but the later does no longer exist in the traditional way. The more I think of it, the more I tend to favor integrating Workstation&Spins into Fedora Linux instead of merging Silverblue+Kinoite, because of the changed condition of “Fedora Linux” box and the reliable availability of Docs in Silverblue/Kinoite.

Yet, I can live with both: what do other people prefer?

I am - or at least I try as good as I can. Maybe, my wording is sometimes inconvenient due to my lack of English skills. :slight_smile:

Indeed, this is the bottom row (of the user documentation part of the page) and is for meta-information. E.g. we want to have to tools box collecting documentation of various widely used tools in Fedora, referencing to upstream docs as much as possible (but providing useful links to spare users the effort to use Google etc. and sorting out unsuitable or even wrong info) and concentrate on Fedora specific issues. And we want to use partials for that, so that Edition specific docs can reuse text as appropriate. Therefore, it is not really an option to omit the Tools box.

Regarding Workstation, I’m glad you volunteer to write a user guide - or kind of - which provides at least some useful information; in contrast to before, namely no instructions at all or predominantly misleading instructions.

No worries, my comment was not meant that seriously :wink:

What do you think of the concept to get rid of an individual “Workstation & Spins” box as elaborated in my recent three posts? Mostly this (the citation at the bottom), and that (mostly the second part).

I would be really happy if we get something on the page that makes the Silverblue and Kinoite teams happy, within the scope of the existing possibilities. This means

  • one box for Silverblue and Kinoite
  • each box with a title (max about 20 chars) and description (max about 80 chars)

We can include links in the description, additional in the title, or the box at all. So you can have direct links in the description as well as a link in the title to a separate page that provides more extensive explanations. What would increase the information content and positively affect the position in search engines.

There is no hurry. Probably you want to discuss it with the respective teams. Given the probabls release date Nov.15 we need title and description about Nov. 8.

Just a minor nitpick – I don’t like the unqualified “& others”. It is not the end of the world. But I think it might be a bad term to have on a front navigation page because people might feel that they have to click on it to figure out what all “& others” covers. I know the context is there such that people should be able to figure it out. But my preference would be that “others” is more directly qualified as “other desktop environments”. Trying to stick within the 80-character limitation, would the following be OK (78 characters)?

Workstation (GNOME) and Spins (KDE and other desktop environments) for your PC

The following might be another option if you prefer laptops/desktops over “PC”. But it sacrifices “KDE” getting an explicit mention (79 characters).

Workstation (GNOME) & its Spins (other desktop environments) for (lap/desk)tops

100% agreed! Many thanks for the hint. And even more thanks for your suggestions. I think, I would prefer the latter. Gnome is officially the Fedora main desktop (unfortunately, it is IMHO getting worse), so it is mentioned explicitly, all ‘others’ being equal as alternatives.

I’m still thinking about it. On the one hand, we want to highlight and advertise our “Editions”. In this respect, the principle of “a separate ‘box’ per edition” is a no-brainer and “feels right”. On the other hand, it is precisely our edition with the highest download numbers that has not really taken care of its users for years. Completely in flawless harmony with its desktop system.

But it doesn’t fit into the general overview page either. This should stringently refer to edition overarching information. Otherwise, it would not be an overview page.

The alternative would be to leave out Workstation completely, like Cloud currently. I don’t like that either.

I would prefer to continue with our current plan and see how far we’ve come in a year.

What do you think if we add a “Getting started” menu item in the sidebar of the Workstation page and compose a rough guidance along the text fragments I collected here. It needs a bit of textual additions and would be no great, but a hint for beginners. And it would be feasible with our resources.

Yeah, now that you mention it, you are right. That’s indeed unqualified, and implicit arguments should be avoided in general at this place. Your suggestion makes sense. However, I wanted to have KDE included because, on one hand, it is the sole spin we can verify at the moment. On the other hand, and this is the major point, I experienced several times on ask.fedora that there are users who know that they have KDE (because they see the word regularly on their desktop) but who have no idea about “Workstation” or “Spins”, or what and if they have that. This also triggers their search queries on search engines, which are likely to contain only “KDE” but nothing of the other two. So that’s the reason.

I think glb’s first approach is ok:
Workstation (GNOME) and Spins (KDE and other desktop environments) for your PC ,
although I would prefer to have “laptops and desktops” contained. I’m not sure if “PC” in English contains “laptops” (?). In German, “PC” commonly even excludes them.

Another alternative would be a compromise towards going above 80 characters:
Workstation (GNOME) and Spins (KDE & other desktop environments) for desktops & laptops ,
that would be 87 characters.

Anyway, the versions proposed so far seem to be good compromises. So I’m fine with all of them.

Hmmm… tbh it looks to me comparable to the old install guide. I just skimmed it, but at least partly it refers to Fedora 21, and some content assumes that any Fedora needs an active root account. Other parts introduce redundancy with two other Docs guides, and with the major Fedora page. And in general much I read does no longer apply. In some cases, I fear that it can actually make the users’ problem solving more difficult through confusion and misinformation.

We should tailor to the feedback of the survey and the biases about the Docs. If we cannot offer maintained content that adds value, we should not trick users to open our pages. The outcome would facilitate that users again start to avoid hits/clicks on our pages, which also devalues maintained content.

Also, generic/general information that cannot be used to solve problems, or to tailor technologies/packages to the user’s needs, seem to belong to the major Fedora page, not to technical Docs. I agree that we had to partly take over this role in the past because getfedora was download-focused. But now that a “full scale Fedora page” is to come, the draft seems to already take over the role for providing generic & general information about Fedora. We have to be careful to avoid competing with them on search engine hits (SEO), this would harm both pages.

However, I understand your goal to have something on this page beyond a pathetic index, and I absolutely agree with that! I have not yet offered a suitable alternative and therefore, it makes sense to grasp at any straw, including old content.

Yet, in the open Workstation & Spins merge request !2, I am working on an adjusted approach that already incorporates the fact that I cannot maintain more pages (which of course would end up in a pretty pathetic guide). The approach still assumes that Workstation & Spins remain an independent guide with its own box on the Fedora Docs main page (yet, depending on what the Silverblue/Kinoite team decides, I remain open to the possibility of getting rid of a dedicated “Workstation & Spins” box).

I will open a new topic about this to explain the adjusted approach. I hope I can make it by tomorrow or Tuesday so that feedback can be given at the meeting. Stay tuned!

“PC” (Personal Computer) would be understood to include laptops in English. What it sort of excludes is “Workplace Computer”; at least to the degree that one does not consider their work computer “their” computer. But, sort of ironically, “Workstation” is the common term used to refer to one’s “Workplace Computer”. So I think PC is OK for English. But I have no idea how or if that would translate.

As I wrote, the text needs some reworking, of course. The idea is to provide a short getting started, helpful for new Fedora users. It would include and limit to the basic steps:

  1. Download
  2. Create bootable Medium
  3. Short Explanation of the screen(s) in the boot process
  4. Selection of either explore or install
  5. Short explanation of the installation screen up to the first Gnome screen.

That’s easy and quick to produce and might be helpful for new users. And it is maintainable for the next releases.

I just pushed a slightly modified version of the descriptions, that reflects the discussion so far.

@siosm I also modified the description for the emerging desktops, explicitly referencing Silverblue and Kinoite as I did in a previous version. That’s not necessarily the final text! Don’t hesitate to provide us with a better version.
Unfortunately the current CSS of the website does not allow to link the names directly or just to link the title. It must be the complete box. We could adjust the CSS, but that would be a more laborious action and exceeds our resources at the moment.