In the past couple of months we've been very actively migrating the available documentation to a new setup. Today is an important milestone as we've integrated the new documentation site in the Across website. All available documentation for every standard module can now easily be accessed from the single new section.
Both the core projects and all standard modules have always had their own documentation repository. Documentation itself was usually written in Asciidoc and then generated as a separate HTML document, deployed on a static webserver.
We found the flexibility of regular Asciidoc files to sometimes be a bit limited when it came to presenting on - or as - a website. Cross-linking between documents was not very easy, a feature like Edit this page was hard to come by and styling across the different documentation repositories required repeated work in every repository separately.
We had experimented with Gitbook for some modules as well, but the Asciidoc support appeared to be sub-par and after a couple of months we decided to drop Gitbook and revert back to regular Asciidoc generation. It proved to be more stable and less of a hassle.
Not that long ago the first version of Antora was released. Antora is a documentation site generator that:
Antora fit our needs perfectly and came at exactly the right time, so we decided to migrate almost immediately. And today we move from development to production with our documentation site.
You can see the result on the site documentation section. Using our new setup brings several advantages (both in front and behind the scenes):
Even though we already integrate over 20 documentation repositories, the entire site generation is still only a matter of seconds.
If you are interested in our setup, you can check out our main documentation site repository which holds the main Antora configuration.
Our documentation still remains a big work in progress. We currently only migrated all existing documentation to the new format.
Some additional documentation has also been added over the past weeks, but it was mostly a form and not a content migration. As such some modules are still quite lacking in documentation, and you may encounter broken links in several spots.
Revising and updating the documentation is a big task that will take us several months at least. But we're confident that our current setup with Antora is the right one, and it will help us in developing the docs, as well as our users in using them and finding the information they are looking for.