streamline plumbing and README with other docs

Makefile

@@ -1,44 +1,34 @@
 pages   := $(shell find . -type f -name '*.adoc')
-out_dir := ./_public
 
-docker_cmd  ?= docker
-docker_opts ?= --rm --tty --user "$$(id -u)"
-
-antora_cmd  ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/antora vshn/antora:2.3.3
-antora_opts ?= --cache-dir=.cache/antora
-
-vale_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/docs/modules/ROOT/pages:/pages vshn/vale:2.6.1 --minAlertLevel=error /pages
-hunspell_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/spell vshn/hunspell:1.7.0 -d en,vshn -l -H _public/**/*.html
-htmltest_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/_public:/test wjdp/htmltest:v0.12.0
-preview_cmd ?= $(docker_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora vshn/antora-preview:2.3.4 --antora=docs --style=vshn
-
-.PHONY: all
-all: html
-
-# This will clean the Antora Artifacts, not the npm artifacts
-.PHONY: clean
-clean:
-	rm -rf $(out_dir) '?' .cache
+ifeq ($(shell command -v podman &> /dev/null; echo $$?),0)
+	engine_cmd  ?= podman
+	engine_opts ?= --rm --tty --userns=keep-id
+else
+	engine_cmd  ?= docker
+	engine_opts ?= --rm --tty --user "$$(id -u)"
+endif
+
+preview_cmd ?= $(engine_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora vshn/antora-preview:2.3.4 --antora=docs --style=vshn
+vale_cmd ?= $(engine_cmd) run $(engine_opts) --volume "$${PWD}"/docs/modules:/pages:Z docker.io/vshn/vale:2.6.1 --minAlertLevel=error --config=/pages/ROOT/pages/.vale.ini /pages
+
+UNAME := $(shell uname)
+ifeq ($(UNAME), Linux)
+	OS = linux-x64
+	OPEN = xdg-open
+endif
+ifeq ($(UNAME), Darwin)
+	OS = darwin-x64
+	OPEN = open
+endif
 
 .PHONY: check
-check:
+check: ## Run vale agains the documentation to check writing style
 	$(vale_cmd)
 
-.PHONY: syntax
-syntax: html
-	$(hunspell_cmd)
-
-.PHONY: htmltest
-htmltest: html pdf epub kindle manpage
-	$(htmltest_cmd)
-
 .PHONY: preview
-preview:
+preview: ## Start the preview server with live reload capabilities, available under http://localhost:2020
 	$(preview_cmd)
 
-.PHONY: html
-html:    $(out_dir)/index.html
-
-$(out_dir)/index.html: playbook.yml $(pages)
-	$(antora_cmd) $(antora_opts) $<
-
+.PHONY: help
+help: ## Show this help
+	@grep -E -h '\s##\s' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

README.adoc

@@ -1,47 +1,47 @@
-= VSHN Application Catalog
+= VSHN Application Catalog Documentation
 
-This is an https://antora.org/[Antora] documentation website, available at https://application-catalog.docs.vshn.ch.
+This repository contains all the content of the VSHN Application Catalog documentation hosted at https://kb.vshn.ch/app-catalog/.
 
-== Basic Antora Setup
+The content is written in https://asciidoctor.org/docs/what-is-asciidoc/[AsciiDoc] and rendered using https://docs.antora.org/[Antora].
 
-* The documentation pages are stored in the `docs/modules/ROOT/pages` folder.
-* Images are stored in the `docs/modules/ROOT/assets/images` folder.
-* E-book specific files are located in the `docs/ebook` folder, including the https://www.gimp.org/[Gimp] template of the cover.
+[TIP]
+====
+* Writing AsciiDoc is best done using Visual Studio Code with https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[the AsciiDoc addon].
+* For a reference what you can do with AsciiDoc, have a look at https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer’s Guide].
+* Antora is capable of doing many great things with documentation. See https://docs.antora.org/[the Antora docs] to gain insights into the tooling.
+====
 
-== Different Kinds of Antora Websites
+== Documentation structure
 
-There are two possible Antora projects:
+The documentation structure is inspired by the https://documentation.divio.com/[Divio's documentation structure]:
 
-* Those including both a `playbook.yml` and `docs/antora.yml` files; and
-* Those only including one of them and not the other.
+Tutorials (Learning-oriented):: A lesson which teaches you something.
+Location: `docs/modules/ROOT/pages/tutorials`.
 
-The file `docs/antora.yml` defines a documentation component including several modules. It specifies the name and entry point of a component.
+How-to guides (Problem-oriented):: Step-by-step guides to achieve a goal. Location: `docs/modules/ROOT/pages/how-tos`.
 
-On the other hand, the file `playbook.yml` is used to coalesce various documentation components into one website. It specifies the build order and the style to apply to the final website.
+Technical reference (Information-oriented):: Description about the inner ongoings. Location: `docs/modules/ROOT/pages/tutorials`.
 
-If your project only requires to be documented, but does _not_ take the responsibility for the build process of the documentation, you can remove the `.gitlab-ci.yml`, `Makefile`, and `playbook.yml` files.
+Explanation (Understanding-oriented):: Explains the background. Location: `docs/modules/ROOT/pages/explanations`.
 
-On the other hand, projects in charge of documentation building do not always include documentation themselves; in those cases the `docs` folder can be safely deleted, only leaving the `playbook.yml` file.
+== Contributing
 
-== Usage
+Create a new branch to make the changes. After you're satisfied with the changes open a Pull Request against the `master` branch.
 
-. `make preview` to launch a "live preview" version of the documentation.
-. `make html` to create the Antora website in the `_public` subfolder.
-. `make pdf epub kindle manpage` to create the corresponding e-books in the `_public` subfolder.
-. `make clean` to remove all build products.
+=== Previewing Changes
 
-== Docker
+To preview your changes locally, make sure you have Docker or Podman installed.
 
-You can create a Docker image out of this project:
+Just type `make preview` and open your browser at http://localhost:2020. This even provides support for live reload when working on the content. See https://github.com/vshn/antora-preview#livereload[this documentation] for more information about it.
 
-[source,bash]
-----
-$ docker build -t application-catalog -f deployment/main/Dockerfile .
-$ docker run --rm --detach --publish 8080:8080 application-catalog
-----
+=== Adding a New Page
 
-The project includes sample YAML files for a suitable Kubernetes deployment.
+. Create new AsciiDoc (`.adoc`) file in the best matching folder according to the described structure under `docs/modules/ROOT/pages/`.
+. Add the file to the navigation under `docs/modules/ROOT/partials/`
 
-== GitLab
+For removing pages just do the opposite: Remove the file and remove the entry in the navigation.
 
-This project includes a ready-to-use `.gitlab-ci.yml` file for GitLab integration.
+== Deployment
+
+This repository only holds https://docs.antora.org/antora/2.3/standard-directories/[Antora content], no plumbing and tooling (aka the Antora https://docs.antora.org/antora/2.3/run-antora/[`playbook.yml`] and `Dockerfile`) to build and deploy it.
+All pushes to the `master` branch trigger a GitHub action (`.github/worflows/triggerci.yml`) which in turn triggers the https://git.vshn.net/vshn/docs/kb/-/blob/master/.gitlab-ci.yml[GitLab CI job] to build and deploy the content using Antora.

docs/modules/ROOT/pages/index.adoc

@@ -9,4 +9,6 @@ Use the search field at the top of this page, navigate through topics with the t
 
 The product documentation can be found under https://products.docs.vshn.ch/[products.docs.vshn.ch].
 
-TIP: The VSHN Application Catalog is a new offering from VSHN. It concerns running applications on Kubernetes and OpenShift.
+NOTE: The VSHN Application Catalog is a new offering from VSHN. It concerns running applications on Kubernetes and OpenShift.
+
+TIP: Contributions to the documentation are welcome. Just click on btn:[Edit this Page] top-right or head over to https://github.com/vshn/application-catalog-docs[GitHub] where the content source is stored.