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:

• Tackle one of our easyfix bugs
• Join the documentation team and help tackle larger projects
• Submit your writing to the quick docs or update our longer format documentation
• Help us convert long format books into more consumable modular documentation
• Help us implement search or localization or CI
• Join the upcoming Fedora Classroom session about the Docs on 6 August, 2018 at a time soon to be announced. See the classroom page for the schedule.

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