Fedora’s Documentation Website has been overhauled

Today, a lot of hard work and effort from a multi-year process pays off. The Fedora Documentation website, https://docs.fedoraproject.org/, is receiving a major upgrade. Thanks to Adam Šamalík for converting everything to the Antora publication engine, and to many members of the docs team for significant work in converting from DocBook to AsciiDoc format.

Why upgrade the site?

Two years ago Fedora Docs was receiving few contributions and was hard to update. Our build tool, publican, was no longer supported by an active project and wouldn’t run on current versions of Fedora. Additionally, many potential contributors were turned off by having to learn DocBook, an XML markup language for technical documentation, in order to contribute. Lastly, our large book titles were hard to update and difficult to add new content to as their structure had grown so large it was hard to understand the whole book.

The Docs team worked through a public process of meetings and mailing list/IRC conversations and settled on a path forward:

  1. Convert our documentation to AsciiDoc, a simpler text markup language.
  2. Adopt new build tools designed to make static sites from AsciiDoc. We looked at several options and decided on Antora, in the end.
  3. Add build automation to make contributions get onto the website faster and to add more testing.
  4. Look into ways to break up our large content blocks to encourage more contribution.

Today we’ve completed steps 1 and 2 and are announcing work on steps 3 and 4.

If you’re interested in why we chose AsciiDoc or Antora, I encourage you to read the companion article posted on the Fedora Community Blog. It goes into the details behind those decisions.

What’s changed for users?

The new docs site has a cleaner navigation and URL structure. It also has the ability to plugin search easily, which we are working on. We’ve continued the successes we had in the previous release, including highlighting the current version of Fedora, making the docs visually easier to read, and moving more information about our community and contribution to the front page where you can find it.

We’ve also been able to continue our work on Quick Docs, to help you find the information you need to solve your challenge right now in one simple procedure.

What is Quick Docs?

Quick Docs is Fedora Project Leader Matthew Miller’s idea for surfacing the great procedure and problem oriented documentation that has been hidden in the Fedora wiki. With Quick Docs, we started by creating stubs for the most commonly used user documentation. We have been slowly getting that content migrated to the docs site and putting in redirects from the wiki. Right now the information architecture of Quick Docs needs some help, but with the new tooling we are on our way to solving this problem.

How do I contribute to the docs?

There are several ways to contribute to the docs:

I encourage you to contact the Documentation Mailing List or for content issues, Petr Bokoč, or for tooling issues, Adam Šamalík.

Fedora Project community

10 Comments

  1. Bob Moore

    Hi Brian, I am retired and have a fair bit of time on my hands as you can imagine. I have tried to find out how to assist Fedora and the rest of the organisation before but didn’t have any luck.

    I am pretty good in Microsoft Office etc. and have been working on/repairing building computers for about 30 years. I am a relative newbie to Linux but use it as my main PC, so am getting there. If there is any way I can help please feel free to contact me or pass my email addy on to some one who needs assistance.

  2. Michael

    Excellent work. Thanks very much.

  3. Dave Eddings

    I see the new website still cannot be navigated without javascript enabled. Can the navigation pane be made to follow sound webpage design principles, and “degrade gracefully” when javascript is not enabled, such that documents can be navigated?

    I know you’ll probably think it’s a weird request, but Fedora is a unique distribution with unusually good security practices, so its documentation should be accessible to users with unusually good security practices, too.

    Thank you!

    • Brian (bex) Exelbierd

      Dave, this isn’t a weird request. Because we are a volunteer contribution community we haven’t done it because no one has volunteered too. I encourage you to contact Adam directly about how you can submit patches to the theme upgrade this behavior. You may also want to submit those directly to the upstream Antora project so even more people benefit from your work.

  4. Jorge

    Any particular reason AsciiDoc was chosen? Why discard other very popular markup languages used in documentation such as markdown?

  5. sabino

    thanks 1000 for the huge effort.
    I am grateful to you as a fedora’user

  6. Viorel Tabara

    Love the new look, and the response time. Just curious, was reStructuredText along with the RTD server considered?

Leave a Reply

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions

%d bloggers like this: