Decisions around Antora

Decisions to take when starting with Antora which are difficult to reverse and their trade-offs. Everything in the context of using it with IntelliJ.

Prerequisites

This assumes the reader is reasonably familiar with technical writing with IntelliJ and the AsciiDoc plugin. See the page Setup for technical writing for step-by-step guide.

This assumes basic knowledge about Antora. See Using Antora with IntelliJ for an introduction and links.

Why some decisions are different from others

When starting on a new topic, there are some decisions that need to be taken at the beginning and which show their impact only later in the project. So the people involved might want to take the “right” decision.

At the same time:

The impact might not be known in advance.
Future scenarios might be difficult to assess.
Some of those decisions might not be easily reversible later in the process.
It might not be clear which decisions those would be and what the costs or reversing would be.

When talking to IT architects, they call those decisions “architecture decisions”, and they argue to take a structured approach and document assumptions, context, options, people involved and the decisions in an architecture decision record (ADR).

When talking to IT consultants, they claim that there is no single “right” decision, and their answer is “it depends”. See Nicolas Fränkel’s blog post on this topic.

Still, this page tries to help with better decisions when starting with Antora. Continue for one more section to find out how.

How this page helps with decisions

This page has been written looking back at the implementation of some Antora sites, and it welcomes feedback from other users to collect more knowledge.

It focuses on:

Decisions that proved to be difficult to be reversed, so new users should focus on them on their start with Antora.
Shows different options and their trade-off in different scenarios and how this changes over time.
Provides a practical example which is usually linked to this documentation which also uses Antora.
As this guide is part of the AsciiDoc plugin for IntelliJ, it takes the perspective of a technical writer managing the content.

Decisions and possible options

For the future, additional pages might appear here like for example:

Which UI bundle to use, and where to place it?
Where should an author’s playbook be placed?
What should be a component, what a module?

Improving this guide

Each of the pages in the guide has an “Edit this page” link in the upper right corner. Use this to edit the content on GitHub. As an alternative, all content to this guide is hosted in the Git repository of the AsciiDoc plugin in the doc folder, so it can be edited in an IDE like any other AsciiDoc content.

If there are missing features, contact the maintainer via email or create an issue on GitHub.