The Docs team is experiencing a new burst of energy. As part of this, we have several big improvements to the Fedora Docs site that we want to share.
Searchable docs
For years, readers have asked for search. We have a lot of documentation on the site, but you sometimes struggle to find what you’re looking for. With the new search feature, you can search the entire Fedora Documentation content.
Lunr.js powers the search. This means your browser downloads the index and does the search locally. The advantage is that there are no external dependencies: searches send nothing to a remote server and there is no external Javascript required. The downside is that the index has to be downloaded before search is available. Although we compress the index, if you’re on a slower connection, you may experience delays.
While the search is a major improvement, it’s not perfect. The search tool is not aware of the context of your search and can’t offer “do you mean _ ?” suggestions. Also, because many pages have similar titles, you can’t always tell which page has the information you’re looking for. We’re looking into adding more context to the page titles and working with teams to make titles more useful.
Stable “latest” URL
Many times when you link to a page on Fedora Docs, you don’t care about the version number. For example, if you’re writing a blog post that links to the Installation Guide, you’d rather it go to the Installation Guide for the latest version. If you don’t actively update your links to Fedora Docs, they grow stale over time.
We recently added a stable /latest URL for release docs. For example, https://docs.fedoraproject.org/en-US/fedora/latest/ points to the Fedora Linux 35 documentation. When we release Fedora Linux 36, soon, that URL will point to F36 documentation. You can use this stable URL when you want to target the latest released version and only use specific versions in the URL when the version matters.
Redesigning the site
Over the next few months, we’re working on a two-pronged approach to documentation. First, we want the user documentation to better reflect the changes in the Fedora distribution over the last few years. In the meantime, there are great differences in terms of installation and administration, which makes uniform guides difficult to write. In fact, most Editions now have their own installation guide. As a first step, we will split the current installation guide into a guide describing where to find the installation guide for the appropriate Edition. It will also include a generic description of Anaconda that Editions can link to or include text parts. We expect to be able to connect the customization during the Fedora Linux 37 development cycle. As a next step, we will revise the Administration Guide and Quick Docs.
In addition, the Docs team will be selecting an Outreachy intern to work on a redesign of the site. This will include both the graphical design of the user interface as well as improving the information architecture of the site. We want to make it easier for you to find exactly what you’re looking for.
Help wanted
Just like the rest of Fedora, the Docs team is a community effort. We welcome new contributors. You can join us in the #docs tag on Fedora Discussion or in #docs on Fedora Chat.
If you see an issue on any Fedora Docs page, you can click the bug icon on the top of the page to report an issue. Or click the edit icon to submit a correction!
Kappa Wingman
‘Lunr.js powers the search.’
But the search index is large. https://docs.fedoraproject.org/en-US/search-index.js
22 MB uncompressed and 6MB compressed (gzip) to be sent over the internet. The user may only do a few search but 6MB to be loaded (even for users that don’t use search).
Consider using Aloglia Search or MeiliSearch.
Peter Boy
We decided about the search engine along various criteria. One of them was (and is) we don’t want to use a third party search service with all these potential hassles of data protection, tracking, malpractice, etc. We do not want to expose our users to any risk. So it has to be self-hosted. In the end, we ended up with Lunar.js, mainly because it is supported and built in by Antora, the CMS. This makes many things easier and is feasible with our available resources.
Currently, we use an early version and expect a lot of improvement coming, specifically with regard to the efficiency of the download. So, we knew about that weakness and decided to put up with it in the overall context as a temporary limitation.
Kappa Wingman
I see.
By the way, MeiliSearch (backend)is open source and can be self hosted.
May be turn off the telemetry before use.
https://docs.meilisearch.com/learn/what_is_meilisearch/telemetry.html
For front end (loaded in client browser), MeiliSearch has the docsSearchbar.JS.
Lucas
Great improvements! Congratulations to the team involved.
Jon Snow
I think it would be better to provide a server sided search instead of a Lunr.js local browser search.
Apart from better search performance, Fedora will also gain the ability to analyse logs of search queries from users to improve the documentation and to find areas of improvement based on the “most queries” and queries that have 0 results.
Peter Boy
Well, probably, besides the fact, that in “… Fedora will also gain the ability to analyse …” the “will” is a nice abbreviation for “could possibly, in a distant, indeterminable future” 🙂
It is not just a side by side comparison of desirable technical features. The Antora/Lunr.js search was and is the best solution we could implement and can maintain with our currently available resources. And the vast majority of our users experience tremendous improvement.
Folks, it’s not just a matter of all the many beautiful things that are out there. The electricity doesn’t just come out of the socket. It’s primarily a matter of the input we want to feed in as a community.
Eric Mesa
This is incredibly exciting. I don’t access the docs too often because I’ve been using Fedora since 2003, but the project’s programming language pages have been indispensable since some languages use their own package manager and others use Fedora packages.
Peter Boy
Thanks for the feedback.
And interesting remark about documentation of programming languages in Fedora. Could you provide a bit of information what the issue exactly is? In other discussions, it has been argued that we don’t need Fedora documentation, but should simply refer to upstream’s.
Ethyl Mertz
Great! The search function on your website is working. That is an amazing accomplishment for 2022 and a true mark of being up to date on the latest technological advances. Maybe someday the ability to bookmark the page will be added to the docs…although I do not want to dream TOO much! After all, linux is so much better than windows at things like everyday use and gaming that it would be absurd to ask linux docs to be capable of being bookmarked. 🙂
Peter Boy
Thanks. Could you add some information about your bookmark issue? Until now, I didn’t have any issue with bookmarking.
saleem
I think it was a sarcastic comment…
Strategist
Not sure if this is the right place to pass the comment. The fact that there is no offline PDF docs is still a bit of disappointment. With so much of automation on packaging and stuff, would it be possible for the team to put in a CI/CD pipeline to automate creation of PDF docs? My apologies in asking if this is not at all a possibilty.
Peter Boy
I’m not our CI expert. But as I understood our discussion, our current CI line it on its limit. We currently reorganize the repos and will build up a new CI pipeline afterwards. So, there may be an opportunity to add PDFs. But it will take some time. If you have some expertise in the field, please join us at discussion.fedoraproject.org/tag/docs (#docs).
Mr Leslie Satenstein, Montreal,Que
If you want contributers for the docs, is there a way to let people write the topic or section with libreoffice, and for Fedora to have a utility that converts th LO text to docbook? I have to say, LibreOffice with WYSIWYG is far far better than using docbook, for
loop write, compiles, reviews, touchups endloop
I would do some editing and research, if my contribution was accepted as a LibreOffice writer document. LibreOffice is a great tool, because of markup and comments that can be used to explain changes, also to accept/reject changes.
Richard England
I’ve not used it but I understand that the CLI utility called “pandoc” is suppose to allow conversions between “odt” and “docbook”. It is available in the Fedora repo.
I understand that this introduces another step in the process but it may be worth investigating.
Again, YMMV but it sounds like it may be worth investigating.
Leslie Satenstein, Montreal,Que
I will definitely explore pandoc. The newest Linux users are generally the college or university student, who finds errors or wants to write something.
Asciidoc is a LOOP write, compile, study output, correct, ENDLOOP
Too much wasted human time. There are better things to do.
I worked for an internet company that wrote articles pertaining to their business. The rule was: use graphical writer (office or libreoffice), pass doc to editor, who did the markup and then back to the author. The cycle was generally one or at very worst, two iterations.
Peter Boy
In short: Yes, we can.
Some explanation and background: I can empathize with your situation very well. About a year ago I was in the same situation. Writing is one of my main activities, and I have been using LibreOffice and the workflow for submitting manuscripts to the various publishers for years. In comparison, adoc and the git process is a huge step backwards. It is very limited in its ability to support a professional writing, design, review and publication.
As an author, we have to adapt to these constraints of the Fedora documentation.
First I continued to develop my articles in LibreOffice and then converted them with Pandoc. A halfway usable result requires a significant restriction in formatting, basically just body text and simple paragraphs, italics and bold. Just a markup as title is processable.
I then switched to the open source program AsciidocFX (https://asciidocfx.com). At least it feels like in the days of writing using Windows98 and WordPerfect. But for Fedora documentation, it is a viable alternative to OpenOffice, because authoring is very limited in expressive features anyway. Maybe, give it a try. You can get used to it, even if you’re an accomplished writer.
Nevertheless, we can process an article in odt, and I’m looking forward to work with you.
Leslie Satenstein, Montreal,Que
You have made my day.
BTW, I can also checkout the French texts, though French is not my mother tongue.
scott
Love the new site! I use Antora at my work and people constantly look at me like I have magic powers when documenting my work!
I only have 1 idea that I might suggest for your site when you have resources available or… you can tell me if this has already been done elsewhere and I am just missing it. I would love to see a feature popularity vote mechanism for just the docs. As one person already mentioned, they would like to see PDF generating capabilities, what else would people like to see from your site?
Rather than analyze the server-side lunar.js for search history to optimize your docs, use a voting mechanism to que up the most wanted features or missing documentation.
Love the work so far! Great job!
Peter Boy
Yes, we hunt for feedback, comments, improvements, additions, etc. Currently, we have options to comment and edit on the right side of the breadcrumb bar. They are rarely used, unfortunately. They are also hardly noticeable to a reader at first glance. Other readers cannot see them or can see them only with difficulty, a discussion cannot arise.
If you know how to implement a comment capability or other feedback function, you are welcome. Please join us at discussion.fedoraproject.org/tag/docs and open a thread.
tom
Fedora Red Hat The best Linux distribution in the world !! .. Leads to creative innovation and develops groundbreaking technologies.
Version 36 Very stable and high quality Congratulations Fedora
Alyssa Davis
Hey, I had just started on here a couple of weeks ago and I was just wondering if anybody could help me explore Fedora some so i could start doing more with my device?
Gregory Bartholomew
I don’t think there is much anyone can do other than to point you to the various online resources. My suggestion would be just to “lurk” for a while on the various social channels (Discourse, Ask, Matrix, Fedora’s YouTube channel, and of course here on Fedora Magazine). Fedora Linux (and other Linux variants) is quite powerful in terms of what can be done with it. But the trade off is that it normally takes time to figure out how to wield that power. 🙂
Peter Boy
Thanks for your question. You point us to a gap in our documentation. It could inspire a possible documentation project, something like a “how can I sweep my Fedora Desktop off it’s feet” tutorial. I don’t think we have such a guide in our portfolio yet.
To become serious, it might start with question, why did I start with Fedora Linux? What would I like to do at first, and probably next. What is the first barrier to master?
I think, a thread at https://discussion.fedoraproject.org/tag/docs would be the best occasion.
Probably we both can start such a tutorial? We, the Fedora project, could get a nice tutorial, and you could get a perfectly running Fedora for your purpose. 🙂
A short Internet search reveals some examples:
How to get started with Linux: A beginner’s guide
https://www.pcworld.com/article/427298/how-to-get-started-with-linux-a-beginners-guide.html
https://www.udemy.com/course/learning-linux-essentials-taking-your-first-steps-in-linux/
https://www.datascript.cz/en/courses/open-source/first-steps-with-linux/
What are you missing in such guides?
Fedora Workstation
alt+shift toggles language BUT the language icon doesn’t change in the panel
rfsghdrfgh
documentation in polish is very ugly