Upgrade the documentation framework

[mmattel]

STEP 1

• We are currently using Antora in version 2.3.4 which is:
  EOL since end of 2021 and out of supprt since Feb 2022.
• The current version lacks a couple of things including the generation of pdf's (currently inactivated) when using the full Antora namespace - which we already use except one name reference, but this is easy to update.
• During some tests already made, it turned out that upgrading principly works with one exeption. When upgrading Antora, search causes issues.
  • We have a customized "generator" (java script to generate the build), not using the default one to enable search. The former implementors did not add descriptions or comments.
• The complexity of the upgrade is because it has to be evaluated carefully for each docs repo, possible sideffects and of course because of search.
• Docs alone cant continue on try to fix search as we are lacking knowledge.

Complexity: 8

STEP 2

• Upgrade ElasticSearch from version 7.17 (EOL, end of support August 2023) to 8 or 9.
• Docs alone cant continue on try to update search as we are lacking knowledge.

Complexity: 3

STEP 3

• Improve HOW search is working. Currently we show results from all repos which is in the majority of times ineffective and insufficient and causes a lot of user frustration.
• Docs alone cant continue on try to improve search as we are lacking knowledge.

Complexity: 3

STEP 4

• Upgrading Antora would also allow us to start upgrading the UI as a second step. Our UI is HEAVILY outdated and e.g. mobile view is not working well. The bad thing is, that the Antora UI allows to use a customisation on top the default, see Supplemental UI, which we did not use. We customized the default. Note that I did my very best to keep a view css and supporting UI scripts up to date.
• Docs alone cant continue on try to fix the UI as we are lacking knowledge.

Complexity: 8

[micbar]

@mmattel needs help to

• understand why it is not working
• identify the needed resource

[mmattel]

I too would like to know why there are issues because then I would have pointed it out already in detail. The "generator" is JS based and ES is integrated via that generator.

I have done first tests about 18m ago and I would need to redo that tests which take some days to pre-identify pitfalls, speeding up the process. When done we can add helping hands.

The resource needed for step 1 is one with time and knowledge of JS so we can debug together nailing down the cause and finding a solution. For step 2, I need one that knows ES and JS and sysadmin, but it could also be that we figure out not longer going with ES but another search engine. For step 3, the same person is welcomed as he already has profund knowledge about the setup. Finally step 4 requires more resources knowing web stuff at minimum, preferred including antora knowledge.