#1

[This started on a community hack fest thread]Fedora Docs community contribution hack-fest with user communities) where you can see details on use cases. Thank you @ojn @jwf for the encouragement.

Constructive discussion on how to use Antora

(ā€¦ or, how to avoid letting Antora become a barrier for contributors)

  • FUN FACT: Antora is developed on Fedora (with the aim of being cross platform, of course).

Dan Allen, from the Antora team, provides these insights:

Dan Allen from Antora.org
To build on what Sarah was saying, weā€™re not traditionally Node.js developers. Weā€™re actually Java and Ruby developers with almost a decade of experience working on documentation tools. We built Antora for good reason. We felt strongly that there was a void (and yes, that includes Sphinx, which has poor AsciiDoc support). Antora is a new effort to build a documentation site generator around AsciiDoc and Asciidoctor, and to allow content to be sourced from multiple locations by design. We talk about our vision and why we are pursuing it in this blog series. I assure you we understand the needs of documentation teams very well, though weā€™re still always learning.

blaise
I can see that Antora is an initiative to help tech writers who love to write in asciidoc format. If the human is the source of the content, then it makes perfect sense to build tools to support that effort.

Dan Allen from Antora.org
Thatā€™s correct. I was planning a similar point in my response, but you beat me too it. The goal of Antora is to able to produce documentation sites, particularly large-scale and distributed sites (which now includes Couchbase and MuleSoft). Naturally, we want to meet the objectives that come with that goal. How well we achieve it depends on the success of the open source project. We welcome your participation. Join us in the gitter channel ( antora/users ) to discuss in real time.

blaise
itā€™s useful to be able to integrate the compiler output into the content stream.

Dan Allen from Antora.org
Indeed, there are two primary sources of documentation, human-written prose and machine-generated output (and sometimes a hybrid of the two). Antora was designed to be a modular processing pipeline that can field a diverse collection of content. To get the project off the ground, we configured the pipeline to focus on the human-written prose first (the AsciiDoc documents). But that pipeline can be reconfigured to accept content in other ways (perhaps generated by a script, AsciiDoc or otherwise). As the project matures, those will be supported out of the box too. Itā€™s just going to take time. (Rome wasnā€™t built in a day, as the saying goes).

blaise
I suppose what I should propose to the Fedora docs team is that we look into having the tools create output in adoc (similar to the way the tools spit out rST)

Dan Allen from Antora.org
Thatā€™s a good compromise in the short term. The other option would be to look into using a custom generator (a script that runs the Antora pipeline, passed via the --generator option).
One piece of advice Iā€™d like to pass on is to encourage folks not to over-apply Antora. Give it a chance to mature. This would be the same advice Iā€™d give for any software. When all you have is a hammer, everything looks like a nail. Be careful not to fall into that trap.

Dan also shared a link to a series of blog posts about Antora architecture. I recommend them to understand how Antora is taking a comprehensive approach to the technical writing use case.

Dan sent me a PS that I want to share:

Dan Allen from Antora.org
Iā€™m very happy to hear our missions are well-aligned. Weā€™re really just at the tip of the iceberg right now and thereā€™s so many possibilities still to explore.
Please feel free to contribute my comments with the Fedora discussion. I take great care in being honest and transparent, so I assure you Iā€™ll be straight shooter about how to apply and not apply Antora, now and in the future. Itā€™s very important to me that Fedora is successful with Antora (and docs in general), Letā€™s make sure we use it at the right time and in the right place so it stands the best chance of helping that happen (and not giving people the wrong impression). And very likely, how Antora gets used within Fedora will help to shape it in return.

2 Likes
#2

Wow, you conducted an interview with Dan? Cool @blaise! :+1: This was helpful for me to better understand Antora.

This could be of interest to @bex, @asamalik, and/or @pbokoc too.

1 Like
#3

Funny! I didnā€™t think of it as an interview, I was following up on an issue I filed and one thing led to another. I think that it helps to remember that we are all people and if we make a sincere effort to understand each other, it shows in the end.

1 Like
#4

I have 2 main problems with Antora:

  • you canā€™t build some part of website, because you donā€™t have all modules around so the view is different
  • it is not packaged in Fedora
1 Like
#5

This may be something to bring up with the docs teamā€¦ maybe @asamalik @pbokoc ?

Yes!! I noticed that also and was surprised because Antora aims to be a pipeline where you can reuse doc projects.You may find that the doc structure post addresses this point.

After contacting the Antora team, I think we may not be using Antora properly (yet).

We donā€™t seem to have a ā€œantora playbookā€ repository, which could serve as a common source for the mapping of build resources, service discovery, name spacing, search scope, etc. For example, their post about page referencing helped me understand the level of abstraction

per @pbokoc, It seems that we have a repo for a doc template, but that is meant to serve as a starting point for new content. Antora Playbooks are intended to be separate from content.
The Antora Documentation Gitlab repo is an example of a playbook.

I think the antora project would consider Fedora packages because they use Fedora themselves.

1 Like
#6

You can build the whole website using the main repo with the antora playbook: https://pagure.io/fedora-docs/docs-fp-o/

However, that builds the site only from the sources already pushed into the source repositories. For local preview, youā€™d need to edit the site.yml (the playbook) to include the local copy of whatever you want to preview.

#7

(If this looks familiar, it is similar to a post I made on the Sanic forum.)

What should we expect from project docs?

Inspired by the thoughts of @pbokoc and @sanja on the topic of doc structure, I repurposed some examples to serve as discussion points here. If we consider ourselves as consumers of the Fedora docs, I think we owe it to the docs team (I know, some of us wear that hat too) to provide coherent, actionable suggestions.

By way of example, allow me to present a few projects weā€™re all familiar with, because they are similar to and because we donā€™t hear people complaining about the docs:

What makes these docs so special?

  • These docs need to be version specific because the code details may change from one release to the next.
  • They also need to be elastic enough that you avoid repeating material that has not changed.
  • There are many cross references because the same info can be relevant to different contexts (eg. Tutorial, Reference, Release Note)
  • If you look at the source youā€™ll notice the use of symbols like :doc: (which resolves to a URL at compile time) and :term: (which resolves to a glossary entry ).
  • They keep the content and presentation separate, because sometimes the HTML needs to look like a web page and the PDF needs to look like a bookā€¦ or ePub, man page, or even a fancy presentation
1 Like