New Documentation Homepage needs review and help

Project Discussion
#1

I just pushed my latest proposal for the new homepage text to the repo. It should be visible soon at https://docs.stg.fedoraproject.org/en-US/docs/ as link in the upper box ‘Fedora Linux’ (target. currently: https://docs.stg.fedoraproject.org/en-US/fedora/rawhide/ Needs to get adjusted). Look at the last build timestamp in the footer, hast to be past 18:50 UTC.

There are some topics to discuss / decide / improve

  1. Does the navigation bar fit?
  2. Correct Link to Fedora 37 Release Notes
  3. Correct Link to Fedora 36 Release Notes
  4. Thorough review of the ‘Getting Started’ section. The text is largely taken from older texts and adapted. Perhaps the adaptation does not go far enough in some places, e.g. regarding media writers.
  5. The ‘Ask Fedora’ people should improve and add to the section if possible
  6. Should the Community section also mention Matrix and IRC? Then I ask for a corresponding addition to the text.
  7. The “newbie’s primer” section is currently a link to a Quick Doc article. I think we should take this article out of QuickDoc (it doesn’t really fit there. QD is about how-tos.) and integrate it into the docs homepage.

All of these are minor additions. I think we are then ready to activate the pages as planned for Fedora 37 on 11/1.

2 Likes
#2

Great! I will have a look the next days.

Let’s wait if there are some thoughts or preferences from the ask.Fedora people. Otherwise we can maybe derive something from the bottom section of the “Workstation & Spins” guide, which focuses Support & common issues, although we are entering the area of redundancy.

Concerning the title of the “Fedora Linux” box, I will also think of shorter alternatives. What we have at the moment seems to partly describe content of the other boxes. “where to find help in case of difficulties” is then followed by a link to ask.Fedora on the “Fedora Linux” index page, although people with problems should have at first a look at the box of their respective edition. So it might bypass the other boxes.

We also have to “interim” revise the two old “Getting Started” pages. The images they contain, e.g. of the mediawriter, are obsolete and no longer describe the current tool.

I just removed the 32 bit architecture, which is not supported for long. We have to be careful with working on separated fedorapeople accounts too long, because in our gitlab repo this error was already corrected in the meantime and now came back.

Supplement: I have already drafts from the “Workstation & Spins” guide for these two pages. I think they should be reviewed and the language should be improved (I have only written it off the top of my head so far). But it is up to date and may contain sufficient information. Page 1 and page 2 (their approach is described here, avoiding issues like that with the architectures above). Maybe it makes more sense to get them ready for publishing instead of correct the errors of the old pages? What do you think? Transferring these two pages also to the “Fedora Linux” box implies more redundancy. However, I guess these two pages make sense in more than one box.

1 Like
#3

The “join the community” bit here:

https://docs.stg.fedoraproject.org/en-US/fedora/rawhide/#_join_the_community

should probably link to here:

https://docs.stg.fedoraproject.org/en-US/project/join/#_not_sure_where_to_start_come_hang_out_with_us

We have a section there directing people to the Fedora Join SIG. People are always free to jump into discussions, but we’ve always had lots of people who don’t know where to start, and for them, meeting the humans of Fedora is a more protected environment before jumping into teams (which is daunting for lots of newcomers) is the preferred approach. Rationale in the readme here:

https://pagure.io/fedora-join/Welcome-to-Fedora

2 Likes
#4

I just made a revision so that we can use the two pages in getting started. I think they could be published that way. I guess they are better suited than the pages from the old install guide?

Any review would be appreciated, especially from native speaker (or at least, non-German speaker), just to ensure that there is nothing “Germanized” contained that could be misinterpreted or so.

Page 1: Why Fedora? Which Fedora edition, spin, or lab to download?
Page 2: How to create an installation media?
→ the latter seeks a maintainer for the Mac and the Windows section :slight_smile: (see MAINTAINER.md: sub-maintainer of the sections would be sufficient if preferred, I can do the rest, and also align and format everything. It is just the raw procedures and commands on Mac and Windows which I cannot identify and maintain. So providing raw text would be fine, too.)

If agreed, I will merge the pages into main so that a final link can be generated.

1 Like
#5

I like the idea to include the join Fedora project here (and the project itself as well) exceptionally well. I included a short text. It should be online in an hour or so. Maybe you could take a look and improve it?

1 Like
#6

In my opinion, there are some issues with this.

(a)
In general, in remembrance of the old Gutenberg letterpress printing with lead letters: It is too much of a “lead desert”. The paragraphs are too long, too unstructured, too confusing for web online reading (from a UX POV).

(b)
The layout is far too choppy and lacks any kind of guidance and orientation. A layout artist would say: Sprinkle salt in the eyes.

(c)
In other places, it is simply wrong. For example, there is no “default” edition. All editions are equally structured by purpose and task. Naturally, there are more desktops than servers. And more general purpose servers than special purpose servers. But that’s about it.

I would propose:

To make a dedicated section “Why use Fedora” (before “Getting started” in the current text) based on the first part “Why Fedora? What distinguishes Fedora from other Linux distributions?”

Then introduce a new second part " What does Fedora consist of?"
explaining the editions, spins, etc. It would be a combination of the first part of the current “Getting started” section and “Where to get Fedora? Which installation image (editions, spins, labs, …​) is appropriate for me?”

After that, the third section is “Getting started”, which is correspondingly shorter.

Regarding “How to create an installation media” we should describe Mediawriter and dd for Fedora, and just link to Balene Etcher and ventoy for all other OSes.

#7

I just had a look. I think that reads very well. Thank you :100:

#8

IMHO there are some issues with modifications added:

" * Fedora Project Wiki - the official wiki for Fedora Project"

(a) We want to switch from Wiki to AsciiDoc and (b) it is a contributor working page, not intended for getting or providing help. We should leave it off.

" * Stack Exchange - an English language Q&A board, not specific to Fedora"

We are the authoritative source of information not Stack Exchange. We should not refer to third party sources where we have no possibility to intervene on quality and actuality.

“at https://fedoraproject.org/wiki/Communicating_and_getting_help.”

We should transfer that page into AsciiDoc, but not link to it And the page is a mixture of different topcis. May be better to divide it into different texts at that occasion.

#9

Absolutely, I didn’t expect to publish these pages so early. But we need some alternative to the old install guide pages. With them, we would essentially re-publish what has been criticized by users. Another alternative would be to update the old pages (so, only the two that are to be published at the current draft).

Sounds good! I don’t know how much time I will have in the next days. I hope I will be able to spare some time to contribute. → Any Fedorian interested in getting a bit into the Docs, feel free to work on the pages :smiley:

Absolutely agreed.

#10

I just pushed a slight update which tries to take into account various objections and put everything into a publishable form.

Maybe we can still get that in staging for our discussion.

#11

The “Downloads” page contained more issues than I originally thought, but I think I updated/replaced the obsolete/false content: https://docs.stg.fedoraproject.org/en-US/fedora/rawhide/fedora-downloads-info/ (be aware that, from the time of this post, it can take an hour or so until the page is updated with the commits)

Commit aa2540b4:

  • Remove+replace obsolete content around architectures: e.g., modern Mac hardware is no longer x86_64 (changed in 2020). Also, the most recent Atoms I could find with 32 bit are as of 2010. To be more resilient to changes, I made the content a bit more generic and focused on the type of computer at this point. For users who do not know about architectures, I guess this is more helpful anyway. Plus, a comment about how to find out about architectures.

Commit 8ff953c2:

  • There is no Fedora Cloud on getfedora.org (this was replaced by CoreOS)

  • Emerging editions, CoreOS, Labs have to be updated/introduced.

  • Spins are not a niche purpose.

  • Not all installations are equal, and currently there is no install guide.

  • Removal of packages cleanly is important to many (one reason why there is criticism of the live images with the many preinstalled packages) → making clear that dnf cleanly uninstalls.

  • It is no longer correct that most modern systems are x86_64; I think the table is now more suitable to help the users indicate what they are likely to have. Also, “aren’t” and such abbreviations should be avoided in official texts.

  • There is no longer a “DVD image”; that’s obsolete.

  • Fedora IoT is still available for armhfp. But that should be not listed among the major architectures: for most users this is only confusing information (it’s now only added as an additional sentence below the architectures).

  • Media type explanations are not up to date, partly obsolete, partly contradictory. Also, we currently have no “DVD”, this is now “Standard”.

  • The points about architectures are already made above. It is confusing that there are, e.g., “Workstation images” and “ARM images” → Workstation can be ARM, but also something else. The information about ARM issues belongs to the above part about architectures.

  • There are currently no official “Cloud images”, neither supported nor provided.

  • Fedora Atomic was replaced by CoreOS.

  • Although it is of course an interesting topic, Cloud Working Group things do not belong here.

  • The “https://boot.fedoraproject.org” things are no longer maintained and the page notes that this has passed “end of life”. Fedora no longer fits Floppy disks anyway :slight_smile:

  • Standard images are not the sole offline installations: live images are also offline installations.

  • Fedora alternative images are not equal to Fedora Server installation images.

  • Netinst is currently only official at Fedora Server. I suggest to not promote it for all editions. I do not know if there are still issues concerning differences to the original editions when installed with netinst images (maybe someone knows more?).

  • The system data at the end is confusing/misleading: some lines are requirements (15 GB disk space), some lines note the default configuration (neither XFS nor BTRFS are enforced on any edition… in all cases, the user can change the default; the same for LVM). Also, I have Fedora installations of 10 GB. Further, “Everything” should not be promoted (and there is no information about Workstation requirements/defaults in this section). Further, “Everything” has not been mentioned before at all (therefore, its hardware issues should not be added to the last section without any information about it in advance). I guess it makes sense to remove this part for now?

The “Downloads” page still referred at one place to Fedora 21. I think it would make sense if someone else has another review, just in case I overlooked something.

Further, the “Media types” part could be a bit better aligned, but I guess we should first focus the content.

Feel free to check my commits, and let me know if there is any objection about something (or everything), so that I can revert/change.

Supplement: Two additional commits that should be available within another hour or so

Commit 42e27bdf:

  • Correcting format of my links

Commit fdbae2d7:

  • I found another “aren’t = are not” and “you’ll = you will”
#12

Thank you a lot. I think, we should do some additional fixing.

in General: We should really avoid information redundancy.

That refers for the first 3 paragraphs containing information about Editions etc. We already wrote about that and should leave it off here. Instead, the article should concentrate on the final selection step, choose the architecture and the type of deliverable.

There are some additional errors, e.g. we no longer support armhpf

Another inaccuracy is with the standard image.

I’ll add some additions and hope they will be available shortly.

#13

If I read the protocol on the go/no-go meeting correctly, we have still no release candidate. (https://meetbot.fedoraproject.org/fedora-meeting/2022-10-27/f37-final-go_no_go-meeting.2022-10-27-17.01.html). So we’ll have no release at Nov. 1. Next release target: Nov. 15

That gives us additional time to polish up our new texts. Nevertheless, we should now prepare for release, as discussed on Wednesday.

As far as I see, we will then have 2 branches, F37 and rawhide. Or will we give up with the release-specific versioning?

#14

I was a bit confused about that comment, but then I saw you already wrote a whole page about that. Sorry, I didn’t notice the new page about this topic before :smiley: So yes, absolutely, it makes sense to completely remove it from the downloads page.

Until yesterday, I thought that, too. But I saw that we still officially support armhfp for Fedora IoT: https://getfedora.org/en/iot/download/ So because it is only supported for one edition, I made a sentence instead of adding it to the “official architectures” table:

Or do you mean that the support is completely dropped in F37? But even if this is the case, F36 is supported for another 6 months.

Yeah, on other places, I didn’t read about that name before as well (or at least, I didn’t notice). But I wanted to stick with the terms on getfedora.org as far as possible, to make it easier for users.

I like it! Greatly structured, especially the Media Types are now much better aligned! And the page at all now wonderfully fits the initial getting started page, which is followed by the downloads page in the menu.

Just in case of armhfp, I would add a sentence that it is still available for Fedora IoT, and if you have information about that, maybe directly add that F36 will be the last Fedora that contains support for it. We could create a ticket in gitlab to remind us that we have to remove armhfp completely once the support for F36 is dropped in about 6 months.

What do you think of that?

REMOVE

Regarding ARM architecture, Fedora supports only 64-bit architecture, aarch64 or arm8, as of release 37 and newer. The older 32-bit architecture, armhfp or arm7, is dropped.

ADD (if F37 will drop armhfp support even for IoT):

Regarding ARM architecture, Fedora supports only 64-bit architecture, aarch64 or arm8, as of release 37 and newer. The older 32-bit architectures and `arm7` are dropped. `armhfp` is still available for the Fedora IoT edition, but Fedora 36 is the last release supporting `armhfp`. In Fedora 37, `armhfp` support is dropped also for Fedora IoT.

OR ADD (if F37 will keep support for IoT):

Regarding ARM architecture, Fedora supports only 64-bit architecture, aarch64 or arm8, as of release 37 and newer. The older 32-bit architectures and `arm7` are dropped. `armhfp` is still available for the Fedora IoT edition.
#15

Not sure how adding another level of indirection for Silverblue and Kinoite helps. Users are not aware of the subtle differences between the edition status of each Fedora variant so having them hidden behind Emerging Fedora Desktops will be confusing. It was even confusing for me.

The redirection does not get us much either. The minimum would be to add the Silverblue & Kinoite names to the description text for this entry.

Note that this also places the Workstation docs at the bottom but it’s our most used edition of Fedora.

1 Like
Boxes on the Fedora Docs page
Boxes on the Fedora Docs page
#16

If you want to regroup things, I would prefer to go the route taken by the new Fedora websites where we showcase things by categories: The leading Linux desktop | The Fedora Project

Boxes on the Fedora Docs page
#17

We might continue this discussion in the related thread :slight_smile: I answered there.

#18

I actually didn’t write a whole page, but I edited your page. So, it is work by both of us :slight_smile:

The current page is about F36. I didn’t see any armhfp on the koji compose page nor on the test result pages. So with F37 I expect there will be no armhfp anymore. If IoT will still provide armhfp, we have to fix the page, of course.

Regarding your alternative proposals: As far as I know, for F36 there is not only a armhfp IoT version, but for several other variants as well. They are (or were) available at several arm SIG pages.

So your latter alternative seems to be more appropriate.

We discussed on our last IRC meeting that darknao will start today to prepare the repo for F37 release and that we freeze the repo until he has completed that task. So we should wait at the moment.

#19

Just to avoid any myth-making: I didn’t want and don’t want to hide anything. On the contrary, I would like to list also such Fedora achievements, which were not included so far and accordingly were neither visible nor easy to find.

As for the layout, we have to adapt to the current existing design and we can’t do everything we would like to do. Therefore, the grouping of Kinoite and Silverblue into one box. The alternative would be to leave out Fedora Workstation, then there would be room for Kinoite and Silverblue each in their own box.

In a first cut I had it that way - including direct links
(Fedora Documentation :: Fedora Docs). But the text was too long and I had to make it shorter. Obviously, I unfortunately left off exactly that part you would like to see there. Would be great, if you would provide us with an appropriate description of about 80 characters length. Maybe something like “Silverblue (Gnome) and Kinoite (KDE) are featuring …”

Originally Workstation wasn’t included at all. Now they are in the 2nd row after all. Workstation has according to our knowledge no documentation at all. And this site is about documentation.

Unfortunately, Workstation WG did not bother to respond to several messages and requests. So that Workstation doesn’t have to vanish completely again, we are in the process of fabricating at least a replacement solution. But this is not comparable to what the other editions offer.

We should continue our discussion on the ‘box’ pages as Chris suggests.

Boxes on the Fedora Docs page
Boxes on the Fedora Docs page
#20

I asked the IoT team to get some reliable information, because I also can only guess based upon nonbinding indication. I will let you know when I get an answer.

Makes sense :wink:

I posted a compromise at the related topic, which we could consider. It seems the current Fedora website draft does not create a separated grouping for Kinoite+Silverblue (however, I do not know how far this is already final or not).

Anyway, I am also open to discuss getting rid of a dedicated Workstation & Spins guide. It is a compromise to have something contained for the two most widespread Fedoras (Workstation + KDE) and try with another approach to develop it into a full scale guide. However, I will be limited to the new Web-UI install guide and maybe here and there one additional page (such as the backup page). Yet, this can be also shifted into “Fedora Linux” as at the moment, because this is ´both nothing Workstation-/KDE-specific.

As long as we do not know for sure that the new approach of the Workstation/Spins works better than the previous approaches, I think the editions that maintain their Docs themselves should have priority. This might also create some incentives to the other WG / SIG. And if not, then not :wink: They have ask.fp anyway.

So maybe it is really worth to discuss to integrate what I have so far in the general “Fedora Linux” and maybe adjust the description to indicate that general issues including “average and general issues with and without major desktop environments” are contained as well. For example, have my WS/spins topics (which are, as I said, widely general) covered in the “Fedora Linux” box, and within the respective pages, add boxes or sections that indicate how to do this with GNOME and KDE if GUIs are applicable at the topic (this can also affect, e.g., Server with GNOME or so).

Without support from the WG / SIG, I could imagine that this makes most sense anyway: my original idea for a separated guide assumed that the traditional “Fedora Linux release” box will remain in parallel the way it used to be, so that it has to be complemented by something dedicated, but this is no longer the case.

→ For everything further, see the related thread - topic closed in here :slight_smile: