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.
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.
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
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.
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.
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.
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.
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).
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. 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
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.
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.
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
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.
