Docs team started about 5 months ago to plan for a new structure of Fedora documentation that is variant (Edition) oriented. The reasoning was published in a Fedora Community Blog entry and a Fedora Magazine article among others., and discussed in two docs office hours.
Currently, we have an Edition specific documentation for all Editions besides Workstation. And nearly all other variants provide documentation as well.
You can view the current status at User Documentation, whereas the article linked in the Workstation Box will not be published in the current form!
We have now the following options
We drop the Workstation box completely and replace it by a Silverblue box. The current "Emerging Desktops" will change to a Kinoite box. With this comes a decision not to provide any user documentation for Workstation at all. Documentation-wise, Fedora Desktop is then Silverblue and Kinoite.
We decide to provide at least a core documentation. Then, for the launch of Fedora 37 release, we need at least minimal initial documentation, such as a "Getting Started" guide. This would at least give us something for new users. I can offer to create this, provided I have at least 2 days to write it. The goal is to then complete this step by step.
From the point of view of the Fedora project, I would prefer alternative 2. But ultimately, this is a decision to be made by Workstation WG. However, I would like to avoid that we just let the situation just move on and afterwards nobody knows how it came about.
Some resent discussion of docs team:
Workstation & Spins Guide: how to solve ...
Fedora Linux Workstation and Spins User Guide: maintenance strategy
Fedora Linux Workstation and Spins User Guide: approach & examples
Remove Install Guide from main
Peter Boy docs board member
This is not an acceptable option since Fedora Workstation is the desktop variant.
It would be sad not to be included, but I don't want us to create docs just for the sake of being included on a website. The information in the docs should be needed, and should be actively used.
I also wonder about the format here: writing a multi-page document about workstation feels fairly anachronistic. Who nowadays wants to read a "guide" for their desktop?!
There are people who are new to the computer or computers in general still. That would be where that would be valuable. And GNOME itself is very different from most desktop paradigms in use today.
I don't think that we want to get into writing a general guide to new computer usage, though?!
Nor do I think we want to be writing our own generic GNOME guide - GNOME already does that. Linking to that content, or incorporating it into our own site like Ubuntu does, would be cool.
According to the data we have, many workstation users try the current installation guide and complain on ask-fpo that what it describes has little or nothing to do with what the installation media actually offers and is also hopelessly outdated.
Some users have tried to remedy this by writing an article under QuickDocs. At the moment, this is the only possible way out of the misery. But the articles are often also outdated, don't really belong there, and are hard to find.
So, overall there is a need for documentation.
Well, 'Guide' is perhaps a less than appropriate term, 'guidance' might be more appropriate. What is wrong with the server documentation (besides it is still incomplete) or the CoreOS documentation?
Definitely not. But a step-by-step 'guidance' for new users how to come from an iso download to login prompt on a ready to use Fedoraa system?
That's the general strategy by our 'upstream orientation'. We link to upstream documentation (not just general, but as specific as possible) and document Fedora specific shaping.
Option 2 appears reasonable and its rationale was clearly documented in Community blog, and discussed. Should make a change.
Indeed, the original goal of the Workstation box on the Docs page was a problem-oriented approach for users who are no experts, and maybe some relevant links for advanced users, but nothing more. So problem-oriented in terms of structures, e.g., even to know that rpm or dnf are related when it is about installing/updating tools/problems is something that cannot be expected from all non-advanced users. So the structure should have focused, e.g., more on "installation, updating, removing tools" rather than "dnf" or so. That was an earlier structure concept (don't feel bound to anything I present here!).
rpm
dnf
Advanced users go upstream, but identifying the appropriate upstream for a given problem is already a skill (such as identifying the relation to dnf/rpm in installation problems; or generally identifying what is related if something occurs that is unexpected for the user). In ask.fp we see this often. In some cases, interpreting upstream can be a skill too as not any upstream Docs are intended for beginners.
The original approach was to generically write about what is Fedora-specific, link to the related upstream where possible, and explain and sum up for users who are not yet familiar with such topics. This was also intended to make the content resilient to the need for content updates (what is relevant for beginners, does usually not change for years). So something like that would make already a difference for users when existing for the major topics (handling packages, partitions/volumes, general GUI issues, etc.), and with that depth, I guess such an article does not need much maintenance over a long time, except checking links from time to time (I think it goes already deeper than most users need it). With regards to the example, a short elaboration with examples of automation with systemd is applicable for years but something several users would not get done themselves, not even identifying that their issue is related to systemd.
However, I am myself limited to the Web-UI guide once it will come (a guide up to the installed Fedora is the one thing where we explicitly have incentives that users have a demand). Originally, the Workstation & Spins box was intended for the Web-UI guide, and to be released with it.
Having something from the beginning would be, imho, not possible without the WG. The outcome would be sparse or superficial, and just capture search engine hits, which both are major points users complained about. The Docs team will be, as far as I see, have 2 permanent people for all tasks related to Docs, including infra. Maintaining a whole guide is not realistic imho.
However, I guess people that are new to computers in general are no regular phenomenon :)
Nor do I think we want to be writing our own generic GNOME guide - GNOME already does that.
If applicable to an issue that a non-advanced user can experience on his Fedora, and if written understandable for such users, a short page that links the issue, which the user can experience on his Fedora Workstation, to the related upstream Docs would already fulfill the goal :) So, casually speaking, "You have THIS issue on your Fedora?" -> "follow this link, it applies to and helps with your issue!". I agree that redundancy of content does not make sense! Its more or less the pointer from the problem to the solution many need ;)
According to the data we have, many workstation users try the current installation guide
Question: is the plan for there to be a new installer guide, which will be generic enough to cover all the editions and spins that use anaconda? If the answer's no, what's the alternative? Every edition writes its own install guide?
This might be tangential to the discussion, but my view is that making something like quick docs the main focus of the docs is the way forward. Short, independent pages are much easier to contribute to, and allow for organic growth by a broader community of contributors. Having the docs be a small collection of big "books" increases the contribution overhead, and doesn't suit the modern reader.
I think the question is: what type of documentation?
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.
What is wrong with the server documentation (besides it is still incomplete) or the CoreOS documentation?
Book format docs are an appropriate choice for technical documentation, and its appropriate to provide technical documentation for something like server or CoreOS. 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.
Book format docs are not a good solution for end user documentation. No one does that.
Maybe there is scope for a more technically orientated guide to workstation, which might be useful for people who are coming to Fedora for the first time, and want that kind of information. I can imagine covering some basics around:
If we were to do that, I would want to be explicit that it's not a getting started guide for all users, but is instead an optional technical guide. It might end up mostly being links to resources that are elsewhere (there are already getting started guides for dnf and flatpak, for example). We might have to see what it looks like in practice.
...
As this is already very close to the approach we originally had in mind, I would be very happy if the WG would implement that!
Everything else we considered after the original approach was just a compromise to limit workload anyway.
If the outcome also has less advanced users in mind, that would be great. But even if not, maybe other contributors can later add explanatory "tip" boxes or so for such users, if that idea suits the WG. In the end, it's the guide of your WG and you decide what you consider relevant and what you want to have in this guide. Guiding users to the related/relevant upstream is already a strong advancement.
Feel free to check if you can re-use or build on any adoc-files from the original approach to save working time (some of the things you noted are already considered in some of these files; but they are early drafts). These adoc files were intended for this structure.
But also feel free to create a new repo based upon the Docs template in order to replace the existing repo completely. That would be entirely up to you ;)
There is no plan to create a generic installation guide. According to our analyses, that's not possible to achieve. The Editions are too different.
The alternative is indeed: Every Edition creates its own installation and administration guide. And that is, what we already have - except for Workstation. We intend to create a reference style guide for some generic tools, e.g. Anaconda. It is strictly Edition agnostic, but provides the content in 'partials', i.e. reusable text sections. So an Edition's guide can reuse the general description for a (sub)topic including screenshots and can add just Edition specific explanations.
Short, independent pages are much easier to contribute to, and allow for organic growth by a broader community of contributors.
Yes, that's exactly the style of the current Server and CoreOS documentation, different from the previous installation and administration guides.
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 content generally isn't needed.
That is a tough thesis. IMHO, especially non-technical users benefit from a step-by-step guide on how to get from ISO file download to a working desktop. Everywhere I read debates about various distributions, I find strong criticism of Fedora, precisely because of the lack of such documentation. Therefore, non-technical users are always strictly advised against Fedora. And again and again I read that actually interested users have given up. But maybe, it's a kind of selective perception of mine.
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.
I think this is more of a noble wish or a promise that has not been kept.
There is no plan to create a generic installation guide. According to our analyses, that's not possible to achieve. The Editions are too different. The alternative is indeed: Every Edition creates its own installation and administration guide. And that is, what we already have - except for Workstation. ...
The alternative is indeed: Every Edition creates its own installation and administration guide. And that is, what we already have - except for Workstation. ...
Wouldn't it make sense to have a common Anaconda guide, which editions can link to? If we have multiple Anaconda guides, it will be pretty difficult to maintain them as and when changes happen.
IMHO, especially non-technical users benefit from a step-by-step guide on how to get from ISO file download to a working desktop.
I agree that it would be good to have a high-level overview of the installation process, from the point of ISO download. It might be best to have that content on the website, where it can live alongside the download page, though?
If we're going to have a detailed installation guide, I don't think that the Workstation WG is the group to write and maintain it. We are not involved in the development of Anaconda, and we are not docs people - our interests and our activities are focused elsewhere. We're just not able to maintain detailed user docs.
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. I think this is more of a noble wish or a promise that has not been kept.
Even if that's the case, it's still an important goal.
Wouldn't it make sense to have a common Anaconda guide, which editions can link to? If we have multiple Anaconda guides, it will be pretty difficult to maintain them as and when changes happen. ... If we're going to have a detailed installation guide, I don't think that the Workstation WG is the group to write and maintain it.
I will create such a guide in collaboration with the anaconda team, but we will do this directly for the Web-UI anaconda. There is a lack of (personnel) resources when it is about doing the same for the current anaconda tool. The guide will be not explicitly/exclusively for the Docs, among others for the reasons you already noted. For now, we have to make compromises.
But besides the guide that leads the user to the installed Fedora, your suggestions largely resemble what we had planned. So I think this would be already an important thing. If we have to wait some time for WebUI until we have a comprehensive beginner's+installation guide, may it be. I think we should avoid that this becomes a 100% or 0% thing...
@pboy Do not forget that the new Fedora website will serve with much more comprehensive information compared to the old one! E.g., elaborating the editions. And most users should be able to get their USB flash drive flashed using the "Media Writer tool" which is now very explicitly put forward, and provided also for Windows and Mac. So this covers already much more than before.
aday:
Yes, I had started such a guide. And it will provide partials, so that an Edition guide can reuse text but retain readability, flow of reading, etc. An installation guidance is much more than to describe how to master Anaconda. But is is currently stalled. Server docs is the only one that uses Anaconda. And Chris will create that guide for the new Anaconda. So there is no demand for a general guide.
That's a viable alternative as long as you only want to have such a guidance as documentation. As soon as you want to introduce more topics, it won't work anymore. Currently, we link from the Editions Download page to docs or directly to the Editions documentation.
I've had a go at an initial draft of some workstation docs: https://hedgedoc.gnome.org/s/d6ZDEqHIH
The idea is that this will be four pages:
I'd appreciate some feedback: does this seem useful? Is there anything that's missing?
I think that's fine! It is useful, IMHO. If something is missing and what might be missing, we will learn from the feedback of our users and can react to it. Maybe we can use the Quick Doc format to fill in missing information.
For me, 2 questions remain
I've modified the box page:
Fedora Workstation An elaborated Gnome based system for laptops and desktops, also with alternative GUIs (Spins)
W'll take that version as a fallback in case we don't get a text in time.
And it would be really nice if you could link after Workstation Download page to the generic Spin page (https://spins.fedoraproject.org).
And at the end of the paragraph about Workstation in section overview, you have " ...wouldn’t be possible without the hard work of teams and individuals across the entire Fedora community. You could add something like "e.g. the Spins Special Interest Groups".
Everything also is important for the Spins as well, IMHO.
I would really like to showcase all the Fedora assets. That's one of the characteristics in which we differ from others.
what should be the title and description? (and that is quite urgent!)
Maybe:
can the spins also be covered in it, or is that too far outside the scope?
That sounds a bit confusing to me. The docs I've written reference the GNOME help, various GNOME applications, GNOME initial setup... none of that makes sense for the spins.
Yes, could be misleading. How can we accommodate the spins on the page, within the layout constraints, any idea?
(https://docs.stg.fedoraproject.org/en-US/docs/)
I have a pull request open for the new docs here: https://pagure.io/fedora-workstation/pull-request/343
It would be good if someone could review this. Maybe we could discuss it at the next meeting.
Metadata Update from @aday: - Issue tagged with: meeting-request
I'm unable to find the existing (previous?) installation guide at all from docs.fpo. So the installation guide for Workstation edition 35 and 36 is also unavailable now. I think that's unfortunate.
It's true there's significant differences in the Anaconda hub UI among the editions/spins. Netinstall and DVD have repo and packageset options we don't see on Live. Live Workstation has no user creation option, KDE and desktop spins do, as do netinstaller and DVD media. But the bulk of the activity users have questions about: automatic (default) partitioning, Custom partitioning, Advanced Custom partitioning, all share the same UI. I don't think the documentation should get overly opinionated by providing partitioning advice. Just explaining the UI behavior and logic is better because it's timeless, low risk for community members to fix mistakes and keep the doc updated.
While the existing installer documentation did have issues, I don't agree eliminating installer documentation entirely is a good alternative. Nor is rewriting the installer documentation for the current UI which is slated to be replaced in a few more Fedora releases.
:flushed:
While the existing installer documentation did have issues, I don't agree eliminating installer documentation entirely is a good alternative
Although I understand the point, I am not sure if I can agree that it helps to tell new users that they are obligated to create root accounts (which is no longer correct at all) two times because the install guide jumps between different releases down to Fedora 21 (just an example). This can (and has already) caused confusion for users, and at the time users use the install guide, it shapes the first impression of Fedora. And it can make them feel very insecure.
Be aware that not every user has the preceding knowledge to interpret what content still makes sense and what not, or how to adapt if not. People who are new to Linux at all, and who are not secure in this area, are likely to assume that they made something wrong...
Just as an alternative point of view ;)
However, the problem you bring up is already marked in order to be considered this week: https://gitlab.com/fedora/docs/fedora-linux-documentation/release-docs-home/-/issues/4
-> darknao added this issue to this week's meeting.
While the existing installer documentation did have issues, I don't agree eliminating installer documentation entirely is a good alternative.
We started the discussion about new structure of documentation in April. And we have made several attempts to contact Workstation WG about this. But unfortunately we have never received an answer.
The previous installation guide caused a lot of headaches and also contributed to Fedora's negative reputation. It is truly no longer sustainable.
The content is still in the repository, and parts that still apply could be used for a workstation installation guide.
But I think Allan has come up with an interesting concept for a new workstation guide. Even if I don't completely agree with him on the subject, I'm very much in favor of trying it and gaining empirical experience.
And a description of the current Anaconda can be found under Fedora Tools. I'm currently checking if we have enough material to complement the upstream documentation with a Fedora-specific guide.
The new user docs have been merged into our repo now: https://pagure.io/fedora-workstation/blob/master/f/user-docs
Any new issues with the docs can be reported here and tagged with user-docs.
user-docs
Metadata Update from @aday: - Issue close_status updated to: Fixed - Issue status updated to: Closed (was: Open)
Metadata Update from @catanzaro: - Issue untagged with: meeting-request
Log in to comment on this ticket.