Boxes on the Fedora Docs page

Project Discussion
1

Given the proposal we started to discuss at the last meeting, we might put this discussion here instead of waiting for the next meeting.

@pboy 's proposal: https://pboy.fedorapeople.org/fedora/fedora-docs-4.html

Some alternatives that could be discussed:

-“Fedora Workstation variants” (I think Fedora does not have variants; so we might not introduce another confusing type; and it is not a Workstation)

+“Emerging Fedora Editions”, which would be the name corresponding to other Fedora pages, especially getfedora.org (sometimes I also read “unofficial editions”), which is why I think we should comply to that. Alternatively, …

+“Immutable Desktop Editions”, which makes clear what is inside. The description might do the rest. I know someone said that immutable is no longer intended, but both Silverblue and Kinoite authors clearly make this point at the very beginning of their Documentation index (see their current Docs pages). As long as they do so, I suggest to comply to that and keep it compliant to what they do.

Immutable is not too technical I guess. At least, it tells people what they have to look for if they want to know what this is all about: there is no easier way to find that out but by searching for “immutable desktop”. Using a name that does not tell people what is contained in this box is not constructive and might create much more confusion than “immutable”. At the worst, it blurs the difference to Workstation and then people do not know at all which Docs to use.

Most important thing: I think the boxes have to comply to getfedora.org → this is where people get their Fedora and this is the one information they have when they seek any Docs for whatever reason: e.g., “I downloaded and installed Fedora Workstation”. If the Docs then give the different Fedoras different names, users possibly don’t know which Docs to use. So especially for the non-technical users we now want to address as well, compliance among Fedora editions/spins/labs is inevitable. With that in mind, I think there is currently no alternative to “immutable desktop” or “emerging edition”.

However, because we have created a separate category for “CoreOS”, which is also an emerging edition, full compliance would mean to stick with the “immutable” title: this is compliant among documentations and pages and enables the user to get the difference and tells them what to search for if they want to know more. Yet, I don’t think the little “error in compliance” (emerging editions <> CoreOS) would be confusing for people at this very place.

To keep compliance, I suggest to also

-“Fedora Lab special use cases”
+“Fedora Labs”

Everything else belongs to the description I think, and might even create some confusion in the title.

Concerning descriptions in general, I think we should comply to getfedora.org as well and use the first one or two sentences used there: https://getfedora.org/ → Labs "Fedora Labs is a selection of curated bundles of purpose-driven software and content as curated and maintained by members of the Fedora Community. "

Silverblue and Kinoite can be summed together based upon what we have on getfedora: "Fedora Silverblue (GNOME desktop) and Kinoite (KDE desktop) are immutable desktop operating systems aimed at good support for container-focused workflows. "

Worsktation & spins seems to be the only that needs something on itself. Maybe we can adopt the title of the repo? So maybe “Problem-oriented guidance for beginners and advanced users of Fedora Workstation (GNOME desktop) and different spins (other desktops, like KDE)”. Since the Workstation WG does not author/maintain Docs, I would prefer the description to not promise too much.

Some incentives might come from the current “Why Fedora? Which Image?” page draft. It’s descriptions are derived widely from getfedora.org, but puts them in the different context.

2

Now stg: https://docs.stg.fedoraproject.org/en-US/docs/

The “Workstation & Spins” link might be changed:

- https://docs.stg.fedoraproject.org/fedora/fedora-workstation/index.html
+ https://docs.stg.fedoraproject.org/en-US/fedora-workstation-and-spins/ (with en-US being replaced respectively)

I thought this URL makes sense to avoid misunderstandings for Spin users.

3

It’s difficult. I would like to avoid any technical wording here. And even “immutable” requires some technical knowledge ti get it right.

The current getfedora page is not a good guidance, because it will (ir has to) change because of the changes in the editions.

Probably it is best just so say what is is: “Emerging Fedora Desktops”.

Do you know where to find the F37 version of getfedora? Some additional adjustments are needed, e.g. the “wiki” link. That’s deprecated and should be replaced by docs page.

I made the changes in stg. It will take some time until the page gets rebuilt-

4

Well, any information is better than none. We have to offer the users something that helps to distinguish. Also, I am not sure if “immutable” is too complicated. Over time, we had a lot of decisions to simplify Fedora (not just Docs but in the community in general) for beginners & non-advanced users. But many (if not most) are not based upon real measurements of demand but personal opinions of developers and potentially their biases about what beginners need and want. Do we have sources for these determinations of beginners’ demand?

If I review ask.fp, my impression is that using Fedora on itself means that users have no problem with getting getting into “terms” relevant to them, at least if simple search queries are sufficient to clarify. Interpreting such terms seems to be no issue there in my perception (feel free to challenge my argument here, as it is also probabilistic and sort of a personal opinion obviously).

When it comes to users who only want to install and then run the system without the need to do anything else, well, they end up at Workstation anyway (which is intended), and they are unlikely to seek Docs for anything else (in my experience, this group does not use Docs at all but just enter their question in a search machine and if it does not work, they open a topic in ask.fp). On the other hand, this approach can become deterrent for advanced users and other groups in between.

I think the sole reliable source of information about beginners & non-advanced is ask.fedora (we have many beginners there), and maybe it makes sense to review their behavior around the term “immutable”: Search results for 'immutable' - Fedora Discussion So maybe this can be indicative.

Further, I think if someone is unable to understand or get into the term “immutable”, then Silverblue is not appropriate anyway, because its non-advanced guidance for users in general is more limited compared to alternatives (both documentation and on ask.fp). So the term might be even a valuable indicator for (in this respect) “disinterested” users who explicitly only need information about Workstation.

“Emerging Fedora Desktops” is correct and can make sense, but if it stands alone without a clarifying description, this avoids to tell users what the difference is. Distinguishing is a major goal of this page. “Emerging Desktop” alone fails to achieve that if there is no description that offers the user what is needed to distinguish imho. This implies no information for both beginners and advanced users. So I am not sure if it fosters beginners when we avoid the “immutable” term at all.

Just some probabilistic thoughts :smiley:

Btw! Supplement… :smiley: I Just had an idea: what about making a ballot? In the recent ballots we could encourage a lot of beginner and non-advanced users to contribute by announcing and pinning the ballot thread at ask.fp. This might offer an interesting perspective! The related threads (announcement thread in ask.fp and ballot thread here at discussion.fp) might also collect valuable incentives from different user groups. What do you think?

Yeah, you are right. We should indeed “tailor to the future” if we already know that changes are ongoing there. However, maybe seeking a direct collaboration & exchange with the related team makes sense? I do not know who is responsible, but quite sure someone here can help to find out :smiley:

Therefore, unfortunately, I don’t know.

However, I guess the marketing team is related to that and I guess they will know who maintains getfedora. So my suggestion would be to ask this in their Matrix channel or just open a discussion thread here at discussion.fp with the #marketing tag: see Fedora Marketing :: Fedora Docs

Hope that makes sense :slight_smile:

5

The getfedora website is maintained by the Fedora Websites & Apps team. You can find the repository on Pagure
Feel free to send a PR, or open a ticket in this repo.

Please note the website is currently being completely redesigned, and a new version should be released with F38.
The new (work in progress) can be seen on Gitlab.

6

Every box has to have a description. Please, have a look at the page, and probably you have an idea for a proper description? The current text is no longer appropriate and is way too long (max about 80 characters incl. spaces).

Same is true for Fedora Workstation & spins. And in accordance with the other boxes we should describe the ‘product’, not the documentation. Something like ‘Elaborated and easy to use graphical desktop operating system, available in different GUI variants.’

7

@darknao Please could you help me with the boxes page?

  1. For the new boxes ‘Emerging Desktops’, ‘Lab’, 'Tools’and ‘ARM’ a created text according to the mindshare and engineering boxes, and added it to site.yml, but I get apage not found. Locally it works.

  2. The new doc homepage gets the wrong (old) navigation list.

Thanks
Peter

8

I understood your argument the way “immutable” shall be avoided at all. So this is what my arguments were referring to.

We can do a lot of elaboration about Silverblue and Kinoite descriptions and titles here, but maybe it makes sense to involve the people that maintain the documentation of these boxes: @siosm @ngompa @ketudb , you are the maintainer of the respective Docs repos. What do you think? Do you have an idea what you want to have when we refer to your Docs? Title & description? I think your opinion should dominate ours in this respect, you know best what you provide.

Yeah, you are right. I have to adjust it. However, I think a hint that there is a difference compared to what is “behind the other boxes” might make sense to avoid confusions. Unlike other Docs, it is not a product on itself but a component together with established institutions, and it will not be for Workstation/spins what the other Docs are for their respective edition. Yet, the focus should be the “Workstation/spins” product, as you said, and everything else should primarily be on the index page. I’ll provide something with a more Workstation/Spins-focused description soon!

9

The site.yml in your repository is only used for the local preview. If you want to add new components to the main site, that must be done in the main site.yml.
I took care of that. Should be up in ~1h.

The current doc homepage uses the navbar described in the antora.yml file.
According to this file, the navbar is a combination of:

I’m not sure what is the correct navigation list you are looking for, but if it’s this one then you have to edit the antora.yml file to reference it.

10

With max 80 characters in mind:

Workstation and Spins:
“Workstation (GNOME environment) and Spins (KDE & others) for laptops & desktops” → 79 characters.
→ something like that? what do you think?

Fedora Server:
We can shorten it to: “Short-lifecycle, community-supported & latest-technology server operating system” → exactly 80 characters.
→ this is a cut of the version from Fedora Server → I think it well distinguishes Fedora Server against other Servers, and the Fedora Server box against other boxes.

Fedora Labs:
We can shorten it to: “Curated purpose-driven software bundles, maintained by Fedora community members” → 79 characters.

Does that make sense? :smiley:

I just saw that the “Fedora Linux” box at the top with “New users, start here. Experienced users, get the latest information” refers to rawhide. I guess this is to become F37 and thus, remain on the page? If so, I have to admit, that given the content and the reputation of this Docs repository, especially the latter part “latest information” of the description can be interpreted even sarcastic.

If we put this at the top, can we maybe re-open the discussion about setting the Fedora 21< install guide offline? I do not understand how this shall create trust, or serve any purpose any longer (except confusing users). Maybe we can create a place holder referring to ask.fedora if people struggle to get the installation done, or something like that? Of course I am only talking about the obsolete install guide, not the sys admin guide or the release notes.

If people see a major “Fedora Linux” box and “Start here”, they will do so, and if there is an installation guide, they will end up at this one if they seek one.

With this in mind (rm install guide), what about adjusting the description of this box as well?
Suggestion: “General notes & system administration foundations of the current Fedora release” → 79 characters
→ I guess you want to avoid terms that need any technical background also at this place. So I think the “General notes … of current Fedora release” is easy to understand and still contains information indicating something like release notes. The latter part “SysAdmin foundations” makes clear its only the Fedora-common foundations of/for SysAdmin but still that this is about system administration and not “how to begin” (this content is not for very beginners). It might be added that this content is not always fully up to date with the current release, making it sometimes necessary that users have to interpret & transfer a bit here and there → so this is another reason why I would not indicate this a “beginner” page.

An alternative for “General …” would be “Common …”, or add “common” to the latter part, which would be my preference but slightly above 80 characters: “General notes & common system administration foundations of the current Fedora release”

Hope that makes sense :upside_down_face:

11

Folks, I just pushed an extended version of the new variant-oriented docs page.

  • I changed the title & descriptions of the boxes that could be from my perspective the final version. But any suggestions of improvement still welcome, ob course.
  • All boxes (should) have correct links to its target, now.
  • The doc homepage should now have the correct nav bar. Unfortunately, I couldn’t check it locally.
  • The boxes ‘tools’ and ‘labs’ are currently incomplete, I’ll complete it in the next 2 days. Any help appreciated.
  • The homepage text is still in statu nascendi. Nevertheless, comments and suggestions highly appreciated.

As I see it today, we can have the pages in the English version ready to publish middle of next week. So there is still hope we can publish at together with release 37.

Remains the question of internalisation / translation. Currently, when I choose another language, I get the old content, at least in German. How can we handle that?

Some boxes have an unchanged content, so we can reuse the text. But a mixture of languages isn’t nice.

How can we handle that?

@darknao Could you help me again with the Fedora Linux Documentation Home Repo? There is no support for building a local preview. Could you add the respective files? It would make it much easier for me to finish the documentation homepage.

12

There is no translation of staging documents. What you see on stg is actually the translation of the production environment version, hence the content differences.
When we publish the new documentation to docs.fedoraproject.org, translators will have access to it and can start working to have it translated.

Done.

13

Cool! Yeah, looks quite nice.

Concerning the Emerging Fedora Desktops, I would be happy to wait a few days if the maintainers have an opinion about it. They know best what they want / what they provide.

Just the comment of the “Fedora Linux” box is imho a bit misleading and does not make clear what it is and how it distinguishes. We should focus on offering users what they need, and not on promoting the Docs (at this point, the users are already there). If they have a problem, they should focus on the box relevant for them, if they seek general information, the general box might be correct. We should not generally trigger them to the latter if they seek something else. This box is not beginner-specific, and I further guess the beginner group mostly needs problem-solving (which is done in any case in another box). Also, if we say “beginner” and “experienced”, we put already everything together and can spare the terms at all :wink:

Alternatives to think about (based upon the current content in staging):

  • Get the latest information about the current Fedora release
  • Get the latest information about the current Fedora release & general introduction
  • General introduction to the Fedora Linux User Documentation
  • General introduction to the Fedora Linux User Documentation & latest information

… or something like that. The box should make clear, or at least indicate, what is contained (distinguish to the other boxes), and, casually speaking, not tell the users “you do not need to know what is contained, just go there”.

Does that make sense?

A slight little thing to mitigate your worries about too many characters: does it also make sense to remove the “.” in the descriptions? I think “.” is not usual in such a context anyway.

A little question I have (this is not critique): What information does “under your own control” add at the Server box? This is something where you can save characters to achieve the intended <=80 if you don’t like my 80-char suggestion for Fedora Server.

14

Thanks. Works perfectly.

Yes of course. Same is true for all other boxes, I think. If one the maintainers wishes a specific text, we should use it.

I’m not happy with the current text, too. I agree, the description should shortly inform what is inside, so users get a hint, if there might be something they are looking for.

I’ve modified the text according to your suggestions. But I think there is still room for improvement.

The 80 characters are a typical “Editor’s limit”, a bit too tightly chosen, because anyway every author overdoes it, but hesitates not to do it too much. :slight_smile:

That way we had an agreement about the descriptions of the server type variants (and in the absence of the Workstation WG without their participation).

It is about having complete control over all data, functions, configuration and optimization, as opposed to outsourcing server operation or limiting it to managed web space or cloud solutions.

15

Absolutely.

Yeah, a version that makes a clear point about the content without becoming blurred or neglecting one of the content types would be nice. Maybe someone else has an idea. Or maybe we will have another idea in the coming days.

Well, I would say that deploying a server operating system already makes this point. All Fedoras have this in common. Vice versa you could say, Fedora Server can be used for (and within) managed and cloud infrastructures as well (so managed by others than the users). Therefore, this would be a possibility to get down to 80 characters, depending on what you consider more important.

16

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

17

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:

18

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.

19

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.

20

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