docs: document some antora build details

modules/contributor/pages/docs/overview.adoc

@@ -2,21 +2,30 @@
 :figure-caption!:
 :antora-docs: https://docs.antora.org/antora/latest/
 :antora-playbook: https://docs.antora.org/antora/latest/playbook/
-:netlify: https://www.netlify.com/
+:antora-zulipchat: https://antora.zulipchat.com/
+:antora-distributed-components: https://docs.antora.org/antora/latest/distributed-component-version/
+:antora-content-branches: https://docs.antora.org/antora/latest/playbook/content-branches/
+:crddocs-site: https://crds.stackable.tech/
 :diataxis: https://diataxis.fr/
-:documentation: https://github.com/stackabletech/documentation
+:netlify: https://www.netlify.com/
+:pagefind: https://pagefind.app/
+:stackable-crddocs-repo: https://github.com/stackabletech/crddocs
+:stackable-docs-readme: https://github.com/stackabletech/documentation/blob/main/README.adoc
+:stackable-docs-repo: https://github.com/stackabletech/documentation
+:stackable-docs-ui-repo: https://github.com/stackabletech/documentation-ui
+:trunk-based-development: https://trunkbaseddevelopment.com/
 
 We use {antora-docs}[Antora] to write our user facing documentation,
 {netlify}[Netlify] to host it and the {diataxis}[Diátaxis] framework as the guide for the structure of the content.
-The main repository for the documentation is the {documentation}[Documentation] repository and
+The main repository for the documentation is the {stackable-docs-repo}[Documentation] repository and
 each operator and other tools have a `docs` directory from which content is pulled in.
 Have a look at the xref:project-overview.adoc[] to learn about the repositories that are involved in providing the documentation.
 
 == Content structure: Diátaxis
 
 The {diataxis}[Diátaxis] framework is a way to classify documentation content into four groups with distinct use cases.
 
-.Source: https://diataxis.fr/
+.Source: {diataxis}
 image::diataxis.png[]
 
 Documentation exists along two axis: _study_ or _work_; _pracital steps_ and _theory_.
@@ -37,7 +46,7 @@ The guide has to account for different use-cases (i.e. the user is using their o
 Since this kind of information is typically product specific, it is located in the usage guide section of individual operators.
 
 **Reference** information for the Stackable platform entails all the settings and Options in our YAMLs, which we generate.
-The reference is found at https://crds.stackable.tech/ and generated from the https://github.com/stackabletech/crddocs[crddocs repository].
+The reference is found at {crddocs-site} and generated from the {stackable-crddocs-repo}[crddocs repository].
 
 === Style guide
 
@@ -46,16 +55,16 @@ The xref:docs/style-guide.adoc[] contains all the information about the writing
 == Technical bits: Antora, Netlify, Pagefind
 
 {antora-docs}[Antora] uses a {antora-playbook}[playbook] to build the documentation.
-It pulls information from all the individual operators, so their documentation can live in the same repository.
+It pulls documentation content from all the individual operator repositories, so an operators documentation is maintained in the same repository as the code.
 Antora builds a static website which we serve over {netlify}[Netlify].
-The web template of the documentation is also custom made and is developed in the https://github.com/stackabletech/documentation-ui[documentation-ui] repository.
+The web template of the documentation is also custom made and is developed in the {stackable-docs-ui-repo}[documentation-ui] repository.
 
-For search, we use https://pagefind.app/[pagefind] - a static search.
+For search, we use {pagefind}[pagefind] - a static search.
 The search index is generated as part of the build process and no external index is queried during search.
 
-For Antora, the https://antora.zulipchat.com/[Antora Zulip chatroom] is a good place to get help (besides the documentation)!
+For Antora, the {antora-zulipchat}[Antora Zulip chatroom] is a good place to get help (besides the documentation)!
 
-Building the documentation and also the deployment process on Netlify are documented in the https://github.com/stackabletech/documentation/blob/main/README.adoc[README] file of the documentation repository.
+Building the documentation and also the deployment process on Netlify are documented in the {stackable-docs-readme}[README] file of the documentation repository.
 
 == Executable tutorials
 
@@ -76,9 +85,15 @@ This is used for getting started scripts, and in there only for versions of oper
 
 Without this templating mechanism, every release these values would need to be updated by hand (or possibly with a search and replace) with is error prone and time consuming.
 
-== Branch and version structure
+== Branch, component and version structure
+
+The documentation consists of two _components_, the `home` and `management` component.
+All documentation for the operators is in the `home` component, and it is versioned with the platform versions (23.11, 24.3, 24.7 etc.).
+The `management` component contains docs for `stackablectl` and the Stackable cockpit; it is not versioned (there is only a single, current version).
 
-All Stackable repositories use https://trunkbaseddevelopment.com/[trunk based development], and so the documentation is also pulled from different release branches.
-This means that any changes from the `main` branch that should be published in other versions need to be cherry-picked over into that branch.
+The `home` component is actually a {antora-distributed-components}[distributed component], which means that it is split across multiple repositories.
+Each operator repository has a `docs` directory where the docs are found, and in there the `antora.yml` file specifies that the component is `home`, which means that the `home` component is partially defined across all operator repositories.
 
-Antora recommends using https://docs.antora.org/antora/latest/playbook/content-branches/[branches] to organize different versions of components.
+For versions, all Stackable repositories use {trunk-based-development}[trunk based development], and so the documentation is also pulled from different release branches in each repository.
+Each branch contains only a single version, and the `main` branch contains the `nightly` docs version.
+Using branches to structure component version is also {antora-content-branches}[recommended by Antora].

modules/contributor/pages/docs/releasing-a-new-version.adoc

@@ -7,7 +7,8 @@ This process has been automated with scripts, which are found in the https://git
 
 The process consists of two steps: 
 
-. Making a new release branch (`make-release-branch.sh`)
-. Publishing the new version by modifying the playbooks (`publish-new-version.sh`)
+. Making a new release branch (`make-release-branch.sh`).
+. Publishing the new version by modifying the playbooks (`publish-new-version.sh`).
 
 Consult the scripts for details about the required steps, as well as prerequisites.
+Furthermore the xref:docs/troubleshooting-antora.adoc[troubleshooting page] can be helpful to understand and fix Antora build errors.

modules/contributor/pages/docs/troubleshooting-antora.adoc

@@ -1,6 +1,16 @@
 = Troubleshooting Antora build errors
+:antora-xref-docs: https://docs.antora.org/antora/latest/page/xref/
 
 * Netlify build error: `Duplicate nav in nightly@home: modules/ROOT/nav.adoc`
 ** This probably means that there are two branches of the same repository defined in the Antora playbook, that have the same version set.
    They both supply a `nav.adoc` file for the same component and version, and Antora doesn't know which one to pick.
-   Make sure that the release branches have the correct version set in their `antora.yml` files and also make sure that the `main` branch is still set to `nightly`.
+   Make sure that the release branches have the correct version set in their `antora.yml` files and also make sure that the `main` branch is still set to `nightly`.
+* An `xref` or `include` in the `home` component is not found (starting with `xref:home...`)
+** If the page containing the `xref` is also in the `home` component, do **not** include the component name in the `xref`.
+   Read the {antora-xref-docs}[`xref` documentation].
+   Creating a reference to a page and _specifying a component without a version_ means that the link is pointing to the latest version.
+   This is usually not what you want!
+   Omitting the component entirely will instead link to the target page _within the same version_ as the page resides in.
+* Other `xref` and `include` issues
+** Familiarize yourself with the {antora-xref-docs}[`xref` documentation] which explains the syntax in great detail.
+   Unfortunately the xref syntax is a common place to make mistakes, and it is easy to accidently link to the wrong place.