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

That’s our wish (and plan), too. The shift to variant-oriented documentation is one step. Another (more technical) is the promotion of ‘partials’ in Antorra. So you can reuse common parts, retaining the readability and topic focused flow of reading. That way you could efficiently build up a nice documentation for Silverblue and Workstation, as an example.

But, @aday describes nicely a common attitude in Fedora: “… and we are not docs people - our interests and our activities are focused elsewhere.” (Too) Many Fedorians are content to produce a downloadable iso (or rpm) and don’t care about users, usability, making is usable and making it really used, etc. (OK, exaggerated formulation). But that’s a totally different discussion.

A lot of people work (professionally) in upstream projects and happen to be part of the Fedora community, too. That’s specifically true for projects initiated or sponsored by Red Hat. That upstream documentation is not primarily for Fedora and does not eliminate the need for Fedora-specific documentation. And the Developer Portal is perhaps more an example of the current unfortunate situation. It’s not conducive to Fedora documentation being spread all over the place, making it hard to find and hard to read, among other things. No other distribution I know, and especially none of the successful and widespread distributions, is as chaotic and disorganized in its public appearances as Fedora. (But that is also somehow sympathetic and cute)

1 Like

Be aware, I was only referring to the given definition of advanced. Personally, developer does for me not imply advanced. There are software developer who have only minor knowledge of the underlying operating system they are using, or of Linux at all. However, the definition you imply is of course also reasonable.

Concerning the expectation for Docs: From whom? And is this a noteworthy number of people? Why don’t they lobby in the community despite the ease possibility? :wink:

The sole unbiased indication we have from the community is in ask.fp, which was one of the original reasons for the Workstation & Spins guide. However, not every topic from there can be solved by Docs. Thus, we cannot assume ask.fp topics automatically imply Docs need. And another important thing about ask.fp: complaints about missing Docs are very seldom (if we have them at all) when someone has a problem there (keep differentiating: “I think we need Docs” does not imply demand, “I have a problem and couldn’t find Fedora Docs about it, so I ask here” does). So, demand is expressed very seldomly even if the problem could have been solved by Docs. Why? One possibility is that they were not even searching for Docs. This means that even if the problem could have been solved theoretically by Docs, there is a likelihood that Docs had make no difference because that type of user has not sought it.

This leads back to your argument: expectation for Docs… from whom, and is this representative? :wink: Again, I did not say that it is wrong to say “I think we need Docs”. I just say that this is an opinion and no proven fact. But an opinion can of course be correct. The underlying question is: is there a noteworthy demand? This means users who have the need for Docs to solve given problems, and the capability+interest to find+use these Docs (all has to be true for Docs to add value). And if so, why does supply keep not satisfying it?

My arguments at the moment do not go in any direction in terms of Docs Yes or Docs No. Just about differentiating between facts and assumptions.

I am not sure if I get your points, but if I do, Peter already elaborated that this is part of the current approach. And it was the major idea of the “Workstation & Spins” guide. E.g, this. So, focus the page on the very problem, and bring all relevant upstream together by providing links. And then explain what is necessary so that also non-advanved users can make sense of all that. In some cases, their problem can be linked upstream and they just need to follow links (if the upstream is comprehensible for non-advanced). In other cases, upstream needs some elaboration because it is itself written more for advanced. However, the approach failed due to the lack of contribution, and at some point, I had to decrease my workload due to other obligations.

Originally, the plan was to make Workstation & Spins for the future WebUI, because this is the one type of guide (“up to the installed Fedora”) where we got incentives from users that there is a need (but we also do not know if this demand is really representative!). Then, it was intended to add articles like the above example around it over time if necessary. However, it will take much time until WebUI gets released, and given the absence of contributions, the Workstation & Spins remains with the original example page for now.

I never said anything else. I described current facts, not assumed needs: people of Fedora are contributing to Docs, but they do it upstream. That’s a fact, and it does not say anything about demand. So it is neither for nor against your argument.

One addition: you will find bad posts and complaints about any product on the Internet if you look for it. It is unlikely that there will be ever a product does not gain criticism from any side. Be careful with assuming that such criticism is everywhere. Because especially from within the community: I do not see much activities to lobby for more Docs, or problems where Docs are mentioned as potential problem solution. Of course this captures not the users who do not use Fedora but who considered it - but we do neither know if there is a noteworthy number of such users, nor can we tailor our Linux to everyone (people have also other obligations: Docs need much time → lack of resources).

However, I think you imply an underlying point on which I agree: On one hand, Fedora is partly developed towards non-advanced users (hide grub menu, decrease customization possibilities in the install to simplify, and so on) despite some criticism from advanced users. On the other hand, there are the arguments that we do not need Docs that are comprehensible/reachable for everyone, as you expressed. So, Fedora develops at different places in different directions, and the outcome can be that both sides deter the respective other target audience. So there is a lack of direction atm.

1 Like

Agreed. :slight_smile:

Just because the working group doesn’t have much time for documentation doesn’t mean that we don’t care about users or the final product! Quite the opposite. It’s just a question of the scope of the task, and the bandwidth that our group has.

i think that it makes sense for the Workstation Working Group to own docs over which it has authoritative knowledge. What’s the default filesystem setup? Which repos are included by default? What are the system requirements? That kind of thing.

For wider scale user documentation, we just don’t have the resources to keep things up to date.

What I would like to see for the docs is to have two sets of content:

  1. A limited series of short multi-page guides, each of which owned and maintained by the relevant team. This would be the guides to CoreOS, Workstation, Installer, and so on.
  2. A larger collection of single page articles, which can be easily written and edited by anyone, and which has a broad community of contributors. This would operate in much the same manner as a wiki, with the docs team playing an editorial and curation role.

The main goal of this strategy would be for the core Fedora community to reduce the amount of time it spends writing docs. There are too few of us and too much content to be written. We need to enlist a wider community to do the writing, with the core teams playing a coordination and QA role.

2 Likes

That would cover technical documentation and comprehensive documentation but there is something missing there that is probably more important than either.

There needs to be a simple guide to getting started that covers the basics.

  • How to logout/shutdown/reboot
  • How to launch an application
  • How to install/remove software
  • How to update the system
  • Basic, commonly used keyboard shortcuts
  • Links to upstream documentation where appropriate

Imagine you are new user. You login and are sitting at a mostly blank screen with no idea what to do next. Linux is attracting more non-technical users and these users need a helping hand to get them moving in the right direction.

I agree and have argued for this for a while now but there seems to be little support for it so I have more or less given up that this can happen.

D’ac­cord! And I am very relieved that we will have workstation documentation.

The first thing we need now is a title and a description text for the box on the docs start page (https://docs.stg.fedoraproject.org/en-US/docs/). Should it be Fedora Workstation or Fedora Workstation & Spins?

Second, we need a repository that we can link to.

There is already https://pagure.io/fedora-workstation/workstation-docs/, which is for the Workstation WG, as far as I can see. There would be now the possibility to use the repository also for user-docs or to create a new repository fedora-workstation/workstation-userdocs.

Alternatively, you can create a new group Workstation in fedora · GitLab and then create a repository in it, e.g. userdoc.

There are different opinions as to which is better.

And third, we need at least a short launch text by the end of the week if possible.
This can be something very short, like Fedora CoreOS has (Fedora CoreOS Documentation :: Fedora Docs Staging)
Still, if a getting started guide should be included, I could help (by the way, all of our Edition documentations have a getting started section, besides Server. Funny, the latter is what I wrote :slight_smile: ).

It’s all a bit short notice now, but still doable, I think/hope.

The docs team will be able to help, I think.

IMHO, that’s what we already have.

Part 1 is the main part of the docs landing page, with references to the Editions documentation.

Part 2 is “Quick Doc”.

Well, I would see the docs team as part of the “core Fedora community”, but I, too, sometimes have the impression that I am more or less alone in this. :slight_smile:

2 Likes

Please, join our docs team and take over responsibility for Quick Dos. Quick Docs is the next task we will tackle once the current docs site change is complete. And we are looking for an editor-in-chief who will work with the necessary intensity to improve and re-focus. Seriously.

While I appreciate the thought, me joining the docs team would only create discord on the team and not move anything forward. My vision is too different philosophically I think.

What makes such a difference?

This could also be written by me or by anyone else (or at least almost) from the docs team.

I feel that the best way to get reasonable documentation on a community driven distro is with broad community involvement.

Likewise, I feel strongly that the way to encourage and engage the community is by making it painfully easy and providing instant gratification to contributors.

For me, that means:

  • Minimal governance
  • A simple way to modify documentation in-place that requires no special skills
  • Changes are published immediately without review

Of course, that alone isn’t enough, but for me, it is the foundation on which the documentation should be built.

From prior conversations, that type of approach doesn’t seem aligned with the way we do things for Fedora.

In general, I think that spending less time discussing documentation and virtually no time writing documentation about documentation would provide more time to actually write documentation.

Of course, that is just my personal bias and beliefs. That is why I think I would be a poor fit.

To be clear, I am not criticizing or complaining, I am just trying to answer your question.

Sort of! I think the main things that are missing are:

  • A docs site that makes the “quick docs” its main focus
  • Atomic quick docs pages - no big tree for navigating them, the ability to edit each page individually
  • An easy way to contribute changes, or add quick docs pages (sadly the current workflow makes contributing changes way too hard)

When I said “core Fedora community”, I was referring to the docs team!

1 Like

I’d prefer to draft out the content I have in mind, to see if it will work as a resource, before we commit to creating a new repo and so on.

I’ll try to get to that as soon as I can, but I have a few other things that I need to take care of first…

In the first design, I positioned Quick Docs more prominently (https://pboy.fedorapeople.org/fedora/). But unfortunately, the current CSS doesn’t flow in 2:1 proportion. We have to fix that first.

Navigation, i.e. Categorization, makes it easier to find information. Apart from that, each page stands on its own and can be edited on its own. This is already significantly different from the documentation Fedora 26 and earlier (and as a remnant of the current installation and administration guide, the former of which is gone now and the latter is going to get replaced).

Each documentation item has an edit button at the top. It opens an easy way to modify the page. It’s very similar to a wiki.

See above. Most of it is already there. One real difference is “lone wolf” versus “community action.”

That’s OK. But I’m wondering what that exactly means. Does this mean that there may be no workstation documentation (and no workstation “box”) at all, or is it just a matter of aptly phrasing the title and description?

Ahh…It is nothing at all like editing a wiki. You have to create a fork and go through a PR/MR process. That isn’t even remotely simple or easy.

That being said, we have debated this to death so I don’t think there is a point in doing so again.

Nothing in what I have described above is “lone wolf” from my perspective. The important part is ease of use and instant gratification. Click edit, make a change, see the change live on the site.

This is very simplified, works for a small project. Fedora is too big to manage this way. When we want to grow in the speed as the Fedora Linux distribution does, we have also to use the same tools as we use there.

For the moment to develop Fedora Linux it works smooth this way, because it is used a long time this way, and already all other Linux projects work with git too.
Imagine if Gnome or other projects would use the same tools as we do for their documentation, it would be as easy as to fork what they have and just add the fedora specific stuff to it. We would not have to discuss about workstation & spins guide.

We could share instated where to find their docs and who is doing what to get up to date with our versions we want to publish. When you see it this way, a wiki is just a handbrake and not really an accelerator for our documentation.

The problematic of missing hands for the documentation is less the amount of willing people, it is more the fear to get into a new process of work. I do include my self in that. But i will not put myself under pressure because of this. There are a lot of other things I can do and being useful for Fedora.

Take it easy, but take it :slight_smile:

I have to say the way it allows reader to contribute/edit is too hard - the toolings need special skills and various access rights to use.

Personally, whenever I see some mismatch between the document and the real product, I would like to point it out (the content) . But I never manage to use the provided tools correctly. I am filtered out naturally in the process.

May be, two tiers of contributors can be cosnidered:

  • tier 1 is to just contribute to Contents (which I hope I can do)
  • tier 2 is based on tier 1 contributions, and submit it via the official toolings

In this way, more reader will join as tier 1. And as the size of tier 1 grows, there will be more capable person to master the toolings and become tier 2.

And slowly, overall contributors to Fedora Docs will increase.

Further, as a start, no need to manager tier 1 and tier 2 initially at the Docs site.

May be, the Docs site and make the below to happen easier:

  1. Each Page of the Docs, will be mapped to the same discussion thread in Ask.FP.O
  2. People can contribute to that page as Replies, so that is tier 1.
  3. Tier 2 will monitor the posts (or wider reader of Ask will prompt it to Tier 2s), and submit those good one to Docs.
2 Likes

Using Discourse as a bug tracker for the docs sounds like an interesting idea. I guess there would just be a special tag or workflow for those submissions? I think I like that idea. Maybe we can create that section somewhere after the two Discourse sites (ask & discussion) are merged.

Also, thanks for offering to help out with the documentation!

1 Like

This kind of thing is specifically why I created the Team Workflows category — subcategories of that can be exactly this kind of thing. I can create something after the merge… or whenever you want.