Redesign Docs front page layout- Outreachy Project 2022 (Help required)

Project Discussion
,
1

Hi everyone! I’m Anushka, a 3rd-year undergrad at IIT Roorkee, India. I am contributing to Fedora Docs as per the project mentioned on the Outreachy website.

After going through the website, I felt a need to create a visual hierarchy for navigation- for which I have thought of 3 levels- a broad distinction ( eg
Introduction, Fedora Linux, other OS, Contribution etc.), then the second level with their subparts, and a third level for “on this page” navigation.

I need some help as I’ve been reading the documentation for some days but couldn’t make sense of many things, so I think I’d like to connect with the people who wrote the documentation or know best about it.

WRT the current website, I have thought of these buckets at the moment:

1.The Fedora Project: About Fedora Project, Fedora Council, Teams( Eng., mindshare, div&inclusion, Program management)
2. Operating Systems: Fedora Linux, Core OS, Fedora Kinoite, Fedora Silverblue, Rawhide
3. Fedora Linux: Releases(newest to oldest), Get started (Quick Docs), Packaging Guidelines
4. Contribute: Gsoc, Outreachy, other contributions

There are some topics, e.g.:

  1. Fedora Server for which I don’t have clarity on whether it should go inside Linux or some other bucket.
  2. Also, where should the EPEL Packaging guidelines go- are packaging guidelines specific to Fedora Linux, or are they general for all OS.
  3. Which bucket should Fedora IoT go to?
  4. Should Fedora Linux Rawhide be a part of Fedora Linux?

Please suggest changes, if any, in the above-mentioned buckets. I welcome suggestions about anything that is missing but could be a part of fedora docs. Putting up this thread for the same.

Looking forward to some clarity, please help!

6 Likes
2

Thanks for asking questions! I know it can be intimidating, but these are really good questions and suggest areas where we’re not telling our story very well. :slight_smile:

I was going to answer the questions point-by-point, but I think a more holistic answer is helpful. I’ll try to be thorough, so please forgive me if I explain too much.

The Fedora Project is a community that produces Fedora Linux. “Fedora Linux” is the generic term for the operating system and is a good default when you’re speaking about the OS broadly. However, we don’t just ship one thing, we have multiple variants—variations in packaging, configuration, et cetera designed to meet particular use cases or showcase certain technologies.

There’s a special class of variants that we call Editions. Editions are selected by the Fedora Council to be our primary offering in a certain market segment. Our current editions are:

  • Fedora Workstation: our main desktop offering, featuring the GNOME desktop environment. This is what we’d expect most people to run on their desktop or laptop.
  • Fedora IoT: a variant designed for Internet of Things use cases
  • Fedora Server: a variant designed for server use cases

In addition, we have a few variants that are sometimes called “emerging editions”. This isn’t a term defined by Council policy, but it’s essentially “things that are not yet editions but we expect will become editions some day”

  • Fedora CoreOS: designed for running container-based workloads, provides automatic updates
  • Fedora Silverblue: a desktop-focused variant that uses a technology called “rpm-ostree” (as does CoreOS and IoT) to provide a “reprovisionable” (sometimes called “immutable”) operating system
  • Fedora Cloud: designed for running in cloud environments (e.g. Amazon Web Services). This was an Edition and was removed due to inactivity but will be targeted for re-promotion in F37.

Beyond those, we have other variants. Although we’d like to move away from these terms, they’re still in use, so I’ll explain that “Spins” are variants of Fedora Linux that feature desktop environments other than GNOME (for example, KDE Plasma, which I use) and “Labs” are variants of Fedora Linux that target specific use cases (for example, the Python Classroom Lab is intended for use when teaching Python to students). Spins and Labs have fairly wide latitude to customize what they present to users. At a low level, most things are the same, but—particularly between desktop environments—the graphical user experience is often rather different.

In addition, we produce Extra Packages for Enterprise Linux (EPEL). This is a rebuild of Fedora source packages for enterprise Linux distributions (e.g. Red Hat Enterprise Linux). It’s not an installable operating system on it’s own, but a suite of packages built from what we ship in Fedora Linux. So the EPEL packaging guidelines would be included with the packaging guidelines. They’re essential a special case of the guidelines for the rest of the project.

In your buckets, I’d suggest changing “Operating Systems” to “Variants” and then I think that’s a reasonable starting point for conceptualizing the content. Some (most? all?) of the teams might better fit under “Contribute” as well.

Does this help?

4 Likes
3

Hi, @bcotton. This has cleared a lot of confusion around how fedora works- especially the variants. I think it was not evident in the documentation that all other OS environments other than Fedora Linux are variations in what(?) I’m clear on this now.

For this point, I would like to know is there any future terminology in the pipeline right now, or do you have to think about them?

Also,

Teams would come under contributing because teams are made under the Fedora project for contributors if I understand this correctly?

There is just one more question I have in mind right now- what is fedora rawhide? I opened the documentation but it looks similar to Fedora Linux 35, 4 etc.?

Other than that, I think I’ve good enough content to kick off some iterations now. Thanks!

1 Like
4

It’s our development branch from which releases are branched.

1 Like
5

Hi! Thank you so much for the help. This was the page I was looking for but couldn’t find:)

2 Likes
6

“Solutions” is the term the Fedora Council settled on.

Right. Teams are groups (sometimes using labels “Special Interest Group (SIG)”, “Working Group (WG)”, etc) that work on specific things within the project. Docs, for example, is a team. The organizational chart in the docs might help with understanding.

Fedora Rawhide is the development branch. Every six months, a Fedora Linux released branches from Rawhide. F36 branched in February, so what’s currently in Rawhide will become F37. The Releases page has some information, but this is something we could probably stand to make more clear. (Not just in the docs, but in like explainer videos and the like, too)

2 Likes
7

Hi everyone, I am Oluwaseun, an outreachy applicant working on improving the fedora doc page. Thank you for this question @likeanushkaa … The response gotten from here is enlightening.

2 Likes
8

After going through fedora documentation page, I created an architecture for the content on the page, however I realize I might have missed some things. Thank you @bcotton for this response, it was really helpful.

I just need clarity on some things though.

  1. Is fedora linux one of the fedora variants or it is a version of fedora workstation(as in fedora linux 36, fedora linux 35,… )?

  2. Also, does fedora kiniote also belong to emerging editions of fedora as well?

1 Like
9

Fedora Linux is the generic term. All variants are Fedora Linux. So when we talk about the variants collectively, we use “Fedora Linux”. Matthew Miller, the current Fedora Project Leader, wrote a Community Blog post that might help with understanding.

Fedora Kinoite is not an emerging edition. To use an analogy, Fedora Kinoite is to the KDE Plasma spin as Fedora Silverblue is to Fedora Workstation. Since the KDE Plasma spin isn’t an Edition, Kinoite isn’t an emerging Edition. Does that make sense?

5 Likes
10

I think its a bit clearer now… Just to confirm I got you clearly, are you saying that Fedora Linux is the generic name for all Fedora products. Fedora Workstation is a variant of Fedora Linux, and that Fedora Linux 36, 35, and the rest are versions of Fedora Workstation?

Oh! I now clearly understand why Fedora Kinoite is not an emerging edition. The analogy was so helpful. Thank you @bcotton for your response.

2 Likes
11

Yes.

Yes.

Not quite. For each Fedora Linux release, we have a version of each of the variants. For example, Fedora Linux 35, which was released in November 2021, includes:

  • Fedora Workstation 35
  • Fedora Server 35
  • Fedora Cloud 35
  • …

Does that clear it up?

4 Likes
12

Wow! Didn’t think of it this way… Yes, it is really clear now. Thank you @bcotton

4 Likes
13

Hi @subtle_influencer . Thankyou for adding on to the discussion,it cleared some more doubts I didn’t even have at the moment. I think it’s clear now how Fedora works :smile:

Thankyou for the clear explanation @bcotton !

4 Likes
14

Hi @mattdm , I believe you’d be a better person to review an information architecture I prepared for the docs website since you have defined the terms in your blog and know best about them.

Here’s the Figma link: https://www.figma.com/file/7nsbTWEsQGZQQOLD8xg8Fd/Fedora?node-id=0%3A1 you can also see some major issues I found in the website which could be worked upon.

Suggestions are welcome!

3 Likes
15

Great work with many incentives @likeanushkaa ! Concerning your argument about the search engine, you are absolutely right: this is already in development. You can test it at Fedora Documentation :: Fedora Docs Staging (this is yet just a test page; @darknao does some great work on that).

You can find the related discussion on

3 Likes
16

Hey, this is amazing. I do have some design suggestions, I’d add in the thread by eod today:)

I’m happy to see search in action!

2 Likes
17

I’m not Matthew, but I do have a few comments on the design.

Information architecture

  • I don’t think including the packaging guidelines under the “Fedora Linux” category is a good fit. It looks like most of the content you included under Fedora Linux is user-facing, but the packaging guidelines are primarily for contributors. (They’re useful as a reference for users who want to make their own packages, but that’s not the target audience)

Issues

  • “There is no way to get back to the main Fedora website…” So I’d argue there is no “main Fedora website”, which is perhaps another problem in itself. But I assume you mean getfedora.org. I agree that it would be good to have clear links to that site—and probably Ask Fedora¸ too—for people who want to get to downloads after reading docs.
  • “No introduction of topics to help a new user…” Agreed. Some of the questions that I’ve answered from Outreachy applicants—particularly around the different variants—have made it very clear that we’re not explaining things well to newcomers. I don’t know how much we could address that on the front page versus an explainer page clearly linked from the front page, but it’s definitely something we should keep in mind.
  • “The dropdown opens a list of topics different from the list of topics actually available on the landing page of the website”. That’s intentional, as each module provides its own navigation. That prevents the navigation column from being so full as to be entirely unusable. That said, many modules could use some additional curation so that the navigation makes sense and is somewhat consistent. I do think the user docs should more closely (but not exactly) reflect the front page.
  • Relatedly, how do you think we could make the navbar and breadcrumbs be less confusing? I do think they both serve different purposes, so we want them both and we don’t want them to be identical. But we do want them to be helpful.
  • “A lot of content is repetitive”. What’s the issue with the repetitive content? (Assuming they all pull from the same “source” so we don’t have to update 10 different places). The idea is that people shouldn’t have to jump to many different places to find out what they need. So if you’re looking at the Installation Guide or the Sysadmin Guide, you should still see the minimum hardware requirements, for example, because we don’t expect that you should have to read both.
2 Likes
18

We do still redirect fedoraproject.org to getgedora.org. Would not be fedoraproject.org the right place to catch up with introduction of the projects and all the topics of it?

19

Hi, @bcotton -

So should it be mentioned in the contribute category?

I have updated the same link: https://www.figma.com/file/7nsbTWEsQGZQQOLD8xg8Fd/Fedora?node-id=0%3A1 with thoughts around this ( under solutions, navigation 1&2)

WRT the solution I propose, since the user can now toggle easily between different articles, I wanted to point out that - for example for releases- inside Fedora Linux- a section about Hardware overview can be mentioned once, and release notes can be another section with f35, f34, f33, etc. as topics inside it. This way the user can visit the hardware overview from any release note.

There isn’t exactly a problem with repetition of content, but it’d make the docs website more organized if articles are mentioned once properly IMO. And we should explore ways of redirecting the user to that one page whenever they would require it.

Please review the files again, as I’ve updated more content!

20

This page might also be the point where people could be made aware of the docs, especially as some may start at this page when they seek help. But the docs are not even mentioned or indicated:

However, obvious links could be integrated into getfedora, both for docs and the intro.