After quite some time using the veteran Sphinx-Doc platform to manage ownCloud’s documentation, we’ve decided to migrate to Antora.
We’re excited about the move and think you will be too; here’s why.
Developers and other community members have told us that while Sphinx-Doc is very capable and feature-rich it was frustrating for them to contribute to the documentation. Whether they were trying to document an app or other code contribution, or trying to correct a mistake or add missing information to the documentation, they’ve been reluctant to contribute.
They told us that this is for two reasons:
- Sphinx-Doc’s file format (reStructuredText) along with Sphinx-Doc’s extensions is too cumbersome.
- Sphinx-Doc is challenging to set up.
As a result, they feel it’s too much hassle even to make a small change. That’s something we’re determined to change — especially as ownCloud is an open-source platform. We want it to be as easy as possible for anyone to contribute to the documentation.
So, after lots of research and experimentation, we decided to find an alternative documentation platform, one that has the following characteristics:
- As quick and painless as possible to contribute — no matter the size of the contribution.
- Uses a file format that’s as similar to Markdown as possible.
- Makes it trivial to navigate through the documentation — regardless of version.
- Makes it easier to release documentation changes — no matter how big or small.
After considering a number of alternatives, we found one that meets all these criteria — it’s called Antora. Antora is self-described as:
The multi-repository documentation site generator for tech writers who ❤️ writing in AsciiDoc.
While relatively new (at the time of writing at release 1.0.2), it’s already an extremely capable tool; one I expect will make developers’ lives much more comfortable and lead to a significant increase in documentation contributions.
This is because Antora is:
- Based around the AsciiDoc format, a format far more akin to Markdown. Its syntax is readable, concise, comprehensive, +extensible+, and, above all, easy to learn.
- Provides a logical and structured way of organizing technical documentation.
- Enforces a clear and logical separation of text content and supporting assets (such as images, videos, and code).
- Uses a small set of tools, ones that are commonly available in developer toolsets, such as Node and Git.
- Provides very flexible project navigation.
- Natively links to different documentation versions within the UI;
- Plus so much more!
What’s Been Achieved So Far?
The migration to Antora’s not finished yet, but we’re excited to share the progress we’ve made with you. In the screenshot below, you can see what the new implementation looks like.
The new Antora based documentation UI of ownCloud
You can see it has:
- The standard main navigation at the top (1).
- The secondary navigation down the left-hand side (2).
- Breadcrumb navigation above the main content (3).
- The main content in the large pain on the right (4).
While not revolutionary, the layout uses well-recognized and understood navigation conventions. However, it has a sweet navigational feature. Notice the link right at the bottom (5). If you click it, it opens up a sub-navigation menu.
Version control in Antora
This is an excellent, time-saving feature that allows for direct navigation between different documentation versions (git branches).
In the current documentation, an extra page exists to link to the various versions of the documentation, such as for version 8.2, 9.x, and 10.x.
However, by taking advantage of this feature in Antora, that’s not necessary, thanks to this innovative feature.
I expect that it will make users lives so much easier, as they’ll be able to navigate quickly to the version of the documentation that matches their ownCloud installation.
What Does This Mean For You?
Despite all this change, if you’re an existing contributor to the ownCloud docs — or if you’re keen to be in the future — not a lot is (effectively) changing for you. That said, you will only need to do three things:
- Learn the basics of the AsciiDoc file format.
- Update your toolset so that it supports AsciiDoc and Antora.
- Start contributing to the new documentation repository.
The first two points are outside the scope of this blog post. However, we’ll have follow-up posts shortly, stepping you through both of them. The key thing to bear in mind is that contributing to the docs is becoming a lot simpler than it is now.
We Want Your Contributions
That’s just an overview of why we’re migrating to Antora and what it means for you. It’s been a fun journey so far, and things are just getting started.
I hope that you’re excited by what’s coming, the Antora platform, and being able to contribute to the documentation in a way that’s far easier than it is now. If you have any questions, let us know; whether in the comments or on social media.
Stay tuned for the second part in which I will explain the basic steps how to work with Antora and directly contribute to the documentation system.
