For documentation, we have javadocs, confluence, and our website. Confluence is aging. The benefit of confluence is that non-committers can modify it directly.
Some pros: a) keep documentation closer to the codebase. We'd just work in our github repo b) this is easier for humans and claude/copilot/agents to maintain c) non-committers can still open prs against github. Slightly more friction than confluence, but outside contributorship to confluence has been minimal in recent years d) start fresh with all the 4.x modifications Some cons: a) yet another site for documentation b) another new tech involved I'm looking at what stormcrawler is doing with asciidoc, and it looks pretty good, e.g. https://github.com/apache/stormcrawler/blob/main/docs/src/main/asciidoc/architecture.adoc The asciidoc plugin generates html that is shipped with the code, and the docs are rendered in github. Should we head in this direction? This would be additive for now. We wouldn't remove any old documentation from confluence or modify our site. Are there better options? Best, Tim
