Explore alternatives to Antora for documentation

[NickLarsenNZ]

Important

This issue is not a commitment to replacing Antora. It is just to record the frustrations of the current documentation workflow, look into alternatives, do timeboxed trials, and understand what we then lose by switching.

Acceptance

• List shortcomings of the status-quo (Antora)
• List things we like about the status-quo (Antora)
• Timeboxed trial of select alternatives to understand the tradeoffs

[fhennig]

thanks for creating this issue, I have already taken some notes on the things you mention in the past, see this nuclino page for reference: https://app.nuclino.com/Stackable/Engineering/Why-Antora-WIP-4e7d2405-d938-4b70-b2a4-0314faafeffd

Anyone tackling this: I would suggest to expand the document so we have it all in once place and the Knowledge base seems like a good place for this info

also definitely in favor of hands-on trials of other tools and timeboxing also a good idea!

[NickLarsenNZ]

I think Nuclino makes it hard to discuss it async (as we think of things that could conflict with existing content). Also the openness is nice :)

Either way, this is the issue to track the exploration (so we can get it on the board at some point).

[fhennig]

Alright, i thought it could be a useful format. you can also comment on the document in nuclino if you have specific thoughts of where you disagree! Otherwise my notes can just serve as one reference point I guess :) But I think the final result should include lists in nuclino for reference.