Hey Tim, I love this idea. It seems like asciidoc is a standard. +1
Thanks, Oleg On Thu, Jan 15, 2026 at 3:10 PM Tim Allison <[email protected]> wrote: > 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 >
