Discussing Fedora Docs website improvement

One big advantage of the lunr extension is you don’t need any additional service to handle the indexing. Downside to that is you need to download the index locally. And it’s quite big for our documentation site (~22MB).
I just found out that our staging (and prod) environment doesn’t have gzip compression enabled (which should really help in our case to reduce the bandwidth requirement and loading time).

I’ve created an infra PR for that.

4 Likes

I wouldn’t worry too much about the page load at the moment. To use the page, you don’t have to wait for the download to complete. You can use the page as before. And obviously the delay occurs only at the first call. Afterwards, the cache is used.

We should discuss our concerns with the developers. I would expect they will work on fine-tuning and performance improvements. There are so many options to handle even a large download as the index file. As I understand, the current version is the first release, isn’t it?

Instead of introducing detours, we should look at what we can optimize locally. So maybe we can separate the download even more from the content loading (lazy load), so that the download in progress is no longer active in the address bar and avoid the (really slight) delay in the use of the content area. Or we can display a Text like “Please wait a moment” in the Search field, when you click into it before the download is complete. Or we can optimize the use of the cache.

I think the current design is nice and helpful. I find it extremely positive that the original page content can be seen next to the search result. This makes orientation much easier.

Even without aforementioned optimizations, it is already a huge improvement and is good enough to make it productive.

1 Like

This extension is actively maintained and most of the concerns discussed here are already reported and worked on by the developers. You can follow this kind of discussion over here: https://antora.zulipchat.com

This is still an alpha version (latest is alpha-6), and I’ve already seen some big improvement with the latest one. The index size was around 60MB with the previous version, and it’s down to 20MB now. With gzip compression, I expect something around 5MB.

Some unrelated minor changes you can see on staging:
You’ll now find 3 icons on the top right: “Page history”, “Edit” and “Report an issue”
image

3 Likes

I forgot to mention in our last meeting that the gzip compression is now enabled on staging.
Let me know if you see any improvement in loading time.

2 Likes

I have the impression, it’s a bit faster. Although still a bit long.

But the loading time does not hinder the usual use of the pages, You can do everything that you could do before, without the search function. The search function does not carry any disadvantage. Therefore I think we should introduce it soon. What would we gain from a delay?

2 Likes

First of all, thank you for enabling search!
That is a huge improvement, and was long overdue.

Apart from the longish load time,
one thing I have noticed is that it is often unclear what is the context for the hits.
For example, here are some results from searching for selinux:
kuva
The two identical Troubleshooting rows are actually for Silverblue and Kinoite.
It would be useful to have that information visible in the results,
so that users of those variants know to pick that result,
and others know to ignore them.

Is there a way to add the component name or such to results?

I widely agree, but not fully:

Do we expect that people with limited traffic / slow connections use the docs? I know in most of Europe and the US we no longer think in such dimensions (MB traffic), but that is not everywhere / for anyone the case. Generally, I think that the majority of people who use the docs are in a comparable situation to us, which would make me agree to @pboy, but I am nevertheless somewhat cautious. What do you think? Btw, how much MB is it with gzip?

The gzipped index is ~6MB.

In this case you can ignore my last post :partying_face:

Yesterday, I deployed the latest version of the search extension, which brings us a few improvements like a reduced index size (it’s a little less than 4MB now) and more contextual information in the results:

You’ll also find a checkbox allowing you to search only within the current doc component.

1 Like

According to my impression it is very fast now. Is the index file loaded in the background when the page is loaded? Or is the loading started when you perform a search?

1 Like

It’s loaded in the background. You can see it if you look at the search bar, it’s disabled at first when you load the page (grayed out) until the index is in memory.

1 Like

Today, I pushed 2 new asciidoc related improvements for doc writers:

  • RPM Spec highlighting
  • Datatables support

RPM Spec highlighting

usage:

[source,rpm-specfile]
----
Name:		hello
Version:	2.10
Release:	1%{?dist}
Summary:	The "Hello World" program from GNU
Group:		Unspecified
License:	GPLv3+
URL:		https://www.gnu.org/software/hello/
Source:		https://ftp.gnu.org/gnu/%{name}/%{name}-%{version}.tar.gz

BuildRequires:	gettext


%description
The GNU Hello program produces a familiar, friendly greeting.
[...]

Datatables

Convert table to DataTables (https://datatables.net) using the datatable role attribute.
Can be useful for big tables, if you need data filtering/ordering.
Additional roles can be used to add DataTables features:

  • dt-search: add search box
  • dt-paging: add pagination

You can also alter the styling with the help of built-in DataTables classes, such as display or compact.

Usage examples:
Load csv file into a table and enable the search feature.

[.datatable.dt-search]
[%header,format=csv]
.Statistics per component
|===
include::examples/es.csv[]
|===

Apply classic DataTables styling with display role.

[.datatable.display]
|===
|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
| ccc | 9 | ttt | 2%
| aaa | 987 | www | 18%
|===

4 Likes

What are we up to lately?

First, I introduce the new top nav bar used in our upcoming new Fedora websites. This is not the final version, but more an early preview of what’s coming next.

image

Next is the revision information you can find just below the title, with the authors’ details, revision date, and version.
We can use that information to quickly check if the document has been reviewed for the last version, and when.

New admonitions style, thanks to @likeanushkaa !


Like the nav bar, the footer has been reworked to match the future design used in new Fedora websites.

And last, but not least, darkmode, matching your OS preferences:

2 Likes

The changes previously mentioned have been pushed to the staging environment for review:

Feedbacks are welcome.

2 Likes

This is very trivial, but I think the color of the tiles for Fedora Linux, Fedora Server, Fedora Council etc. is very dark. The color design of the new website feels more “light” to me, personally. I reckon the tiles could be a lighter color, but I don’t have a strong feeling about it. Just some feedback.

I like that very much. 2 Questions:

  1. Originally, we planned to have “Fedora Linux” and “Quick Docs” in the top row, with “Fedora Linux” being 2 tiles in width and “Quick Docs” 1 tile. So it should grow and shrink in 2:1. That doesn’t work in the current CSS. Could we get it fixed on this occasion?

  2. Some users noticed that the icons to edit a page or to create an issue can easily be overlooked. Can we improve that, e.g. by color or a bigger size (but that could decrease the elegance)

1 Like

The homepage is basically pure HTML. You can set whatever classes/styles you need on it.
For instance, you could add style="flex-basis: 600px;" to the Fedora Linux item, and it’ll make it bigger.

I don’t have any solution to that right now but I’m open to suggestions :slight_smile:

2 Likes

Yes, but I think we should use the same CSS as all the other pages to ensure consistency. We may overwrite styles that are specific for the boxes page. But we shouldn’t touch basic elements. E.G. we should change the principal construction the boxes, e.g. using margin or not" Or are the boxes specific for docs start page and never used somewhere else?

We need a fluid design, so we can’t use px. I tried to use a growth ratio for the flex boxes, but it didn’t work as expected. Do you know a css expert we can ask?

That’s true. But consistency is not the issue as all the CSS on this page is very specific to this single page. We don’t have any other page in the documentation that uses this layout.
I also don’t really want to spend too much effort on tweaking this page since we are most likely going to rewrite it entirely at some point in the future.

I’m not a CSS expert, so please forgive me, but I’m not sure why using a px value with flex-basis is an issue with fluid design. We are already using a px value anyway for this exact same attribute (which is currently set to 300px).
If you really don’t want to use px, you can use a percentage, like 33% / 66% (minus the margin).

1 Like